Commits

Jason McKesson committed 7da3774

Documentation update.

Comments (0)

Files changed (6)

docs/Load Docs.xpr

         <file name="Common_Extension_Files.xml"/>
         <file name="Extension_Files.xml"/>
         <file name="Home.xml"/>
+        <file name="Structure_Reference.xml"/>
         <file name="Style_Creation.xml"/>
         <file name="Style_Pointer_C.xml"/>
         <file name="Style_Pointer_CPP.xml"/>

docs/Structure_Reference.xml

+<?xml version="1.0" encoding="UTF-8"?>
+<?oxygen RNGSchema="http://docbook.org/xml/5.0/rng/docbookxi.rng" type="xml"?>
+<?oxygen SCHSchema="http://docbook.org/xml/5.0/rng/docbookxi.rng"?>
+<article xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+    <title>Structure Reference</title>
+    <para>This is a reference manual for making structures. It covers all of the information about
+        valid structure actions, parameters, and the specific interactions with styles.</para>
+    <para><phrase role="toc"/></para>
+    <section>
+        <title>Concepts</title>
+        <para>Structures are defined by a Lua table. Lua's table mechanism is a lot like
+            JavaScript's similar constructs; it makes for a handy data storage format. And since it
+            is a Lua table, it doesn't have to be <quote>parsed;</quote> it's just a valid Lua
+            object. This also allows parts of tables to be used in different places, and for tables
+            to effectively be <quote>copied</quote> by simply using another variable.</para>
+        <para>A structure is built as a nested series of tables. So you would define one like
+            this:</para>
+        <programlisting>local my_struct =
+{
+  { type="foo", },
+  { type="bar", },
+}</programlisting>
+        <para>The contents of the base structure is an array of values. Once you have created the
+            table, the actual datastructure is created as follows:</para>
+        <programlisting>local Structure = require "Structure"
+
+Structure.BuildStructure(my_struct)</programlisting>
+        <para>The return value is a special object that should be returned along with your
+            style.</para>
+        <para>Each element of a structure is called an <glossterm>action.</glossterm> The type of
+            action is defined by the <literal>type</literal> field. Using an invalid type will
+            result in a build-time error (ie: <literal>BuildStructure</literal> will error). This
+            makes it easy to do some basic verification by simply executing your structure's script.
+            It won't verify things like function existence or parameter correctness, but at least
+            you know you've spelled your action type correctly.</para>
+        <para>Each type can have a number of attributes. Some attributes are specific to certain
+            types, while others can be used anywhere.</para>
+        <para>Actions can be nested within other actions. For some actions, it generally does not
+            make sense to nest them, while others are designed for nesting. How the actions nested
+            within an action are processed depends on the type of actions. Actions that iterate over
+            something will execute their contents once per iteration. There are actions that can
+            will execute their contents only if a style-provided function returns true. And so
+            forth.</para>
+        <para>When a structure is processed, each action will be executed in the order provided. Do
+            note that no steps are taken to prevent infinite recursion/iteration; if your structure
+            uses a variable which uses another variable which uses the original, that is a legal
+            table in Lua. Attempting to process with <literal>BuildStructure</literal> will halt
+            with a stack overflow (or execute infinitely).</para>
+        <section>
+            <title>Context</title>
+            <para>There is a notion of a current <glossterm>context</glossterm>. The context
+                represents all of the information currently available to an action (and therefore
+                whatever style code it calls). Some actions will augment the current context with
+                new information. These take the form of parameters passed to style functions.</para>
+            <para>If an action provides some new context variable(s), then all child actions may
+                access that.</para>
+            <para>Some actions <emphasis>require</emphasis> certain context variables to be
+                available. If they are not, then a runtime error will result. For example, the
+                function iterator action iterates over all of the functions within the current
+                extension or version (both of which are context variables). If no extension or
+                version is available, then the action will fail to execute.</para>
+            <para>Similarly, actions cannot modify already existing context variables. So you cannot
+                nest actions that provide the same context variable(s).</para>
+            <para>In the reference table below, there will be text that says, <quote>must be within
+                    the scope of.</quote> This means that the action needs to be inside something
+                that provides this context variable.</para>
+        </section>
+        <section>
+            <title>Current Style</title>
+            <para>When style functions need to be called, the system will use the current style to
+                do so. The style will be the table provided to the generation system.</para>
+            <para>However, it is often convenient for the user to put different functions within
+                tables in a style. For example, you could have a function called
+                    <literal>WriteExtVariable</literal>. When generating your header file, you want
+                it to write an <literal>extern</literal> declaration, but in your source file, it
+                should write it as a non-<literal>extern</literal> definition. What you can do is
+                define a pair of sub-tables of your main style table. A table called
+                    <literal>header</literal> would have one version of
+                    <literal>WriteExtVariable</literal>, while the table called
+                    <literal>source</literal> would have another version.</para>
+            <para>Thus, you could use the same structural element to process both. Like this:</para>
+            <programlisting>local piece =
+{
+  { type="ext-iter",
+    { type="write", name="ExtVariable(hFile, extName, spec, options)", },
+  }
+}
+
+local my_struct =
+{
+  { type="group", style="header"
+    piece,
+  }
+  { type="group", style="source"
+    piece,
+  }
+}</programlisting>
+            <para>When the system goes to find <literal>WriteExtVariable</literal>, it will first
+                check the most recently set sub-style. If it does not find the function there, it
+                will check the next one. And the next. Until it comes to the main style table. If
+                it's not there, <emphasis>then</emphasis> it errors out. Thus, every additional
+                substyle <emphasis>increases</emphasis> the number of functions available; it never
+                reduces them.</para>
+            <para>Indeed, the <literal>style</literal> parameter itself uses similar resolution
+                methods. For example, you could have a second table inside the
+                    <literal>header</literal> table also given the name <literal>source</literal>
+                (so it's full name relative to the main style is <literal>header.source</literal>).
+                If you are inside the <literal>header</literal> style and then ask for the
+                    <literal>source</literal> style, you will get the
+                    <literal>header.source</literal> sub-style.</para>
+            <para>This is a very useful tool for making large structure construction more
+                manageable.</para>
+        </section>
+    </section>
+    <section>
+        <title>Action Reference</title>
+        <para>This is a list of all of the actions and their associated attributes.</para>
+        <para>When an action says, <quote>Provides access to the X parameter,</quote> this also
+            means that the action <emphasis>cannot nest</emphasis> with any action that provides
+            this parameter. Including itself.</para>
+        <glosslist>
+            <glossentry>
+                <glossterm>file</glossterm>
+                <glossdef>
+                    <para>Creates a tabbed-file. See the TabbedFile.lua module to understand what
+                        this is. The default function parameters are: <literal>(basename,
+                            options)</literal></para>
+                    <itemizedlist>
+                        <listitem>
+                            <para><literal>name</literal>: The exact name of a function to call that
+                                returns the full pathname of the file to create</para>
+                        </listitem>
+                    </itemizedlist>
+                    <para>Provides access to the <literal>hFile</literal> parameter.</para>
+                    <para>Note that you really need the <literal>basename</literal> variable. At the
+                        very least, you should extract the directory name from it, as you will need
+                        to attach that to the front of the return value from this function. You can
+                        use <literal>util.ParsePath</literal> for this. Thus, your code should look
+                        like:</para>
+                    <programlisting>function style_name.GetFilenameFunc(basename, ...)
+  local base, dir = util.ParsePath(basename)
+  local filename = --compute filename here.
+  return dir .. filename
+end</programlisting>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>block</glossterm>
+                <glossdef>
+                    <para>Writes the beginning of a block before executing its children, and writes
+                        the ending of a block after executing the children. The default function
+                        parameters are: <literal>(hFile, spec, options)</literal></para>
+                    <itemizedlist>
+                        <listitem>
+                            <para><literal>name</literal>: The base name of a pair of functions to
+                                call to write the beginning and end of the block. The block
+                                beginning function's name will be prefixed by
+                                        <quote><literal>WriteBlockBegin</literal></quote>; similarly
+                                the ending function is prefixed with
+                                        <quote><literal>WriteBlockEnd</literal></quote></para>
+                        </listitem>
+                    </itemizedlist>
+                    <para>Must be within the scope of <literal>hFile</literal>.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>group</glossterm>
+                <glossdef>
+                    <para>Represents a collection of actions. This has no real semantics; it's
+                        mainly used as the base table for variables that contain actions. Every
+                        table in the structure must have an action, so this is used to group them.
+                        They can also have conditional attributes and such.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>write</glossterm>
+                <glossdef>
+                    <para>Calls a function to write something to the file. The default parameters to
+                        the function are <literal>(hFile, specData, spec, options)</literal>.</para>
+                    <itemizedlist>
+                        <listitem>
+                            <para><literal>name</literal>: The base name of the function that does
+                                the actual writing. The full name will be prefixed by
+                                        <quote><literal>Write</literal></quote>.</para>
+                        </listitem>
+                    </itemizedlist>
+                    <para>Must be within the scope of <literal>hFile</literal>.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>blank</glossterm>
+                <glossdef>
+                    <para>Writes a blank line to the file.</para>
+                    <para>Must be within the scope of <literal>hFile</literal>.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>filter</glossterm>
+                <glossdef>
+                    <para>Will execute its child actions only if the given function returns true.
+                        The default parameters are <literal>(hFile, specData, spec,
+                            options)</literal>.</para>
+                    <itemizedlist>
+                        <listitem>
+                            <para><literal>name</literal>: The base name of the function that does
+                                filtering. The full name will be prefixed by
+                                        <quote><literal>Filter</literal></quote>.</para>
+                        </listitem>
+                        <listitem>
+                            <para><literal>neg</literal>: If this is true, then the meaning of the
+                                return value is inverted. That is, if the function returns true,
+                                then it will <emphasis>not</emphasis> process the children. This is
+                                useful for reusing filter functions in opposite ways without having
+                                to write a new one.</para>
+                        </listitem>
+                    </itemizedlist>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>ext-iter</glossterm>
+                <glossdef>
+                    <para>Executes its children once for every extension that the user explicitly
+                        asked to generate code for.</para>
+                    <para>Provides access to the <literal>extName</literal> parameter.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>version-iter</glossterm>
+                <glossdef>
+                    <para>Executes its children once for every version in the specification that is
+                        less than or equal to the one the user asked for. If we are processing a
+                        specification that doesn't have any versions (ie: isn't OpenGL), then none
+                        of the children will be executed.</para>
+                    <para>Provides access to the <literal>version</literal> parameter.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>sub-version-iter</glossterm>
+                <glossdef>
+                    <para>Execute its children once for every version less than or equal to the
+                        current <literal>version</literal> parameter.</para>
+                    <para>Must be within the scope of <literal>version</literal>. Provides access to
+                        the <literal>sub_version</literal> parameter.</para>
+                    <para>This is useful for generating a group of functions or files that do
+                        something for each version, and for each version of OpenGL &lt;= that
+                        version. For example, you can have a bunch of headers that only provide
+                        functions/enums for features introduced within that version. Then, you can
+                        generate a file for each version, which includes headers only for the
+                        contents of everything <emphasis>up to</emphasis> that version of OpenGL and
+                        not just within it.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>core-ext-iter</glossterm>
+                <glossdef>
+                    <para>Executes its children once for every core extension of the current
+                            <literal>version</literal> parameter. Note that this will iterate over
+                        the core extensions introduced in version <emphasis>only.</emphasis></para>
+                    <para>Must be within the scope of <literal>version</literal>. Provides access to
+                        the <literal>extName</literal> parameter.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>core-ext-cull-iter</glossterm>
+                <glossdef>
+                    <para>Executes its children once for every core extension of the current
+                            <literal>version</literal> parameter which <emphasis>was not
+                            requested</emphasis> by the user to be exported. That is, these are the
+                        extensions that you need to look at because they are core extensions (and
+                        thus part of the current version) and won't have looked at already as part
+                        of the regular extension iteration process.</para>
+                    <para>Must be within the scope of <literal>version</literal>. Provides access to
+                        the <literal>extName</literal> parameter.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>enum-iter</glossterm>
+                <glossdef>
+                    <para>Executes its children once for every enumerator within scope.
+                            <quote>Scope</quote> is defined by the <literal>extName</literal> and/or
+                            <literal>version</literal> parameters. If <literal>extName</literal> is
+                        available, then it will iterate over all enums in the extension. If
+                            <literal>version</literal> is available, then it will iterate over all
+                        enums that were introduced within that particular version (and
+                            <emphasis>only</emphasis> them). If both are available,
+                            <literal>extName</literal> takes priority.</para>
+                    <para>Must be within the scope of <literal>extName</literal> or
+                            <literal>version</literal>. Provides access to the
+                            <literal>enum</literal> and <literal>enumTable</literal>
+                        parameters.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>func-iter</glossterm>
+                <glossdef>
+                    <para>Executes its children once for every function within scope. Scope is
+                        defined as for <literal>enum-iter</literal>.</para>
+                    <para>Must be within the scope of <literal>extName</literal> or
+                            <literal>version</literal>. Provides access to the
+                            <literal>func</literal> and <literal>typemap</literal>
+                        parameters.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>enum-seen</glossterm>
+                <glossdef>
+                    <para>This is a special action which records which enumerators were iterated
+                        over within its scope. Every time an <literal>enum-iter</literal> finishes
+                        processing an enumerator, the enumerator name that was processed will be
+                        recorded in <literal>enumSeen</literal>. That allows the user to be able to
+                        detect if this is the first time (inside this scope) that the enum was
+                        processed. This helps styles execute statelessly.</para>
+                    <para>To see if an enumerator was processed already, use
+                            <literal>enumSeen[enum.name]</literal>. The value stored there will be a
+                        string containing the extension name or the version that it was most
+                        recently seen within.</para>
+                    <para>Provides access to the <literal>enumSeen</literal> parameter.</para>
+                    <para>Note that if you place a filter within an <literal>enum-iter</literal>
+                        block that is in an <literal>enum-seen</literal> scope, the filter's
+                        active/inactive status <emphasis>will not affect</emphasis> whether
+                            <literal>enumSeen</literal> will be updated. It doesn't matter if
+                        nothing was written; the enumerator being iterated over is enough.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>func-seen</glossterm>
+                <glossdef>
+                    <para>Works like <literal>enum-seen</literal>, except for functions.</para>
+                    <para>Provides access to the <literal>funcSeen</literal> parameter.</para>
+                </glossdef>
+            </glossentry>
+        </glosslist>
+        <section>
+            <title>Common Attributes</title>
+            <para>Here is a list of attributes that can be used in any action (or at least a lot of
+                them).</para>
+            <glosslist>
+                <glossentry>
+                    <glossterm>name</glossterm>
+                    <glossdef>
+                        <para>Part or all of a function name to call. The name, when possibly
+                            augmented with action-specific text, will used to fetch a function from
+                            the various styles and sub-styles as stated in the Current Style
+                            section. If the name is followed by a parenthesized list of parameters,
+                            then these parameters will be used in that order to call the
+                            function(s). If a particular parameter is not available in this context,
+                            a runtime error will occur. Each action that defines a name also defines
+                            a default set of parameters for functions that don't provide their own
+                            parameter list.</para>
+                    </glossdef>
+                </glossentry>
+                <glossentry>
+                    <glossterm>style</glossterm>
+                    <glossdef>
+                        <para>Adds a new sub-style scoping. It fetches the style table using the
+                            rules specified above in the Current Style section.</para>
+                    </glossdef>
+                </glossentry>
+                <glossentry>
+                    <glossterm>optional</glossterm>
+                    <glossdef>
+                        <para>Normally, the inability to resolve a function name to a function will
+                            result in an error. If this is set to true, then the failure to resolve
+                            a function will simply mean that the function is not called. All
+                            children are processed as though the function had been called normally,
+                                <emphasis>UNLESS</emphasis> it is a filter action. In that case, the
+                            filter will be assumed to have returned false, meaning that children
+                            will not be processed (unless <literal>neg</literal> is set, in which
+                            case it will flip that into <literal>true</literal>, thus always
+                            processing children if the function isn't present).</para>
+                    </glossdef>
+                </glossentry>
+                <glossentry>
+                    <glossterm>first</glossterm>
+                    <glossdef>
+                        <para>If it is set to true, this action (and any of its children) will only
+                            be processed the first time through the most recent iteration loop. This
+                            only works with the <emphasis>most recent</emphasis> iteration
+                            loop.</para>
+                        <para>The interaction with filters can play havoc with this.
+                                <literal>first</literal> will only work when it is the numerically
+                            first time the node is seen within the most recent iterator. If a filter
+                            filters out the first time through, then the first action and its
+                            children will <emphasis>never</emphasis> be executed.</para>
+                    </glossdef>
+                </glossentry>
+                <glossentry>
+                    <glossterm>last</glossterm>
+                    <glossdef>
+                        <para>If it is set to true, this action (and any of its children) will only
+                            be processed the last time through the most recent iteration loop. The
+                            same caveats apply with respect to filters.</para>
+                    </glossdef>
+                </glossentry>
+                <glossentry>
+                    <glossterm>cond</glossterm>
+                    <glossdef>
+                        <para>These are special conditionals that act like single-action filters.
+                            Unlike regular filters, they are pre-defined by the system. When they
+                            are false, the current action and its children will not be
+                            processed.</para>
+                        <para>There are a fixed set of conditions. Most of them match iterator
+                            names. For these, they are considered to pass if the corresponding
+                            iterator would execute at least once. Also, since they are based on
+                            iterators, they can <emphasis>only</emphasis> be used in the same
+                            context that their corresponding iterators can:</para>
+                        <itemizedlist>
+                            <listitem>
+                                <para><literal>ext-iter</literal></para>
+                            </listitem>
+                            <listitem>
+                                <para><literal>version-iter</literal></para>
+                            </listitem>
+                            <listitem>
+                                <para><literal>core-ext-iter</literal></para>
+                            </listitem>
+                            <listitem>
+                                <para><literal>core-ext-cull-iter</literal></para>
+                            </listitem>
+                            <listitem>
+                                <para><literal>enum-iter</literal></para>
+                            </listitem>
+                            <listitem>
+                                <para><literal>func-iter</literal></para>
+                            </listitem>
+                            <listitem>
+                                <para><literal>core-funcs</literal>: Returns true if the spec has
+                                    core functions/enumerators at all. Basically, checks if the
+                                    specification is OpenGL and not WGL or GLX. Technically
+                                        <literal>version-iter</literal> would do the same job, but
+                                    in a less obvious way.</para>
+                            </listitem>
+                        </itemizedlist>
+                    </glossdef>
+                </glossentry>
+            </glosslist>
+        </section>
+    </section>
+    <section>
+        <title>Function Parameters</title>
+        <para>Here are a list of the various function parameters, with references to the actions
+            that provide them.</para>
+        <para>Again, <emphasis>DO NOT MODIFY THEM!</emphasis></para>
+        <glosslist>
+            <glossentry>
+                <glossterm>specData</glossterm>
+                <glossdef>
+                    <para>This is the entire data containing every enumeration, typedef, function,
+                        etc for the specification (OpenGL, WGL, GLX). It is a massive struct, and
+                        it's format is complex.</para>
+                    <para>You can see what specData looks like by reading
+                            <filename>glspecs/glspec.lua</filename>. <literal>specData</literal> is
+                        derived from this table, but with some modifications. The modifications are
+                        detailed in the comments at the top of
+                            <filename>modules/LoadLuaSpec.lua</filename>. They're primarily
+                        convenience stuff, to make it easier to find enums and functions by name and
+                        so forth.</para>
+                    <para>Normally, you should not need to look at this data structure directly. So
+                        include it in a parameter list sparingly.</para>
+                    <para>This parameter is always available.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>spec</glossterm>
+                <glossdef>
+                    <para>This is a struct containing functions used to get specification-specific
+                        strings. This allows the style of writing to be mostly independent of things
+                        like whether it is writing to OpenGL or WGL. For example, if you have the
+                        base name of an enumeration, and you want to prefix it with the spec-defined
+                        prefix for enumerations, you do this:</para>
+                    <programlisting>spec.EnumNamePrefix() .. enumName</programlisting>
+                    <para>There are a number of spec functions that return prefix strings or other
+                        spec-based strings. You can find these in the
+                            <filename>modules/Specs.lua</filename> file, with a comment stating what
+                        each one returns.</para>
+                    <para>There are also some functions that provide general information: list of
+                        versions, list of core extensions, a string containing the definitions for
+                        the OpenGL function to load function pointers, etc. These lists are all
+                        stored in the <filename>data</filename> directory, using the file format
+                            <literal>data/&lt;specName>_spec&lt;data>.lua</literal>.</para>
+                    <para>This parameter is always available.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>options</glossterm>
+                <glossdef>
+                    <para>The options data structure. It contains the options processed from the
+                        command-line. Among these is <literal>extensions</literal>, the list of
+                        extension names that are being explicitly written. You can tell which spec
+                        is being used with <literal>options.spec</literal>, but it's better to rely
+                        on the <literal>spec</literal> parameter as seen below.</para>
+                    <para>This parameter is always available.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>basename</glossterm>
+                <glossdef>
+                    <para>The base filename provided by the user, relative to the current working
+                        directory. You will need this to generate files in the directory the user
+                        wants for <literal>file</literal> action types.</para>
+                    <para>This parameter is always available.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>hFile</glossterm>
+                <glossdef>
+                    <para>A <literal>TabbedFile</literal>. This is a special kind of Lua IO file. It
+                        supports all of the Lua IO methods (<emphasis>DO NOT CLOSE IT!</emphasis>),
+                        but it's designed to handle indentation. As such, it extends the Lua IO with
+                        specialized routines to auto-indent individual lines. This allows the system
+                        to determine the indention to use based on command-line options. The
+                        assumption with almost all of the writing functions is that each write is an
+                        individual line.</para>
+                    <para>This parameter is provided by the <literal>file</literal> action.</para>
+                    <para>Note that you must use it with Lua's member calling conventions
+                            (<literal>hFile:write</literal>, for example). If you try to use
+                            <literal>io.write</literal>, things will break.</para>
+                    <para><literal>hFile:inc</literal> and <literal>hFile:dec</literal> are
+                        functions that increment/decrement the current indention level. The
+                        indention can be preserved with <literal>hFile:push</literal> and restored
+                        with <literal>hFile:pop</literal>.</para>
+                    <para>The <literal>TabbedFile</literal> also offers the ability to do string
+                        formatting directly into the write. <literal>hFile:fmt</literal> takes a
+                        format string and some parameters, forwards the parameters to
+                            <literal>string.format</literal>, then writes that string as a
+                        line.</para>
+                    <para>There are block writing functions, <literal>hFile:writeblock</literal> and
+                            <literal>hFile:fmtblock</literal>. These functions will split the
+                        written string into individual lines and indent each one.</para>
+                    <para>If you don't want indented writes, then use
+                            <literal>hFile:rawwrite</literal> and
+                        <literal>hFile:rawfmt</literal>.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>extName</glossterm>
+                <glossdef>
+                    <para>The base name of an extension. Usually paired with
+                            <literal>specData</literal>, as the name alone isn't terribly useful.
+                        You can get the list of enumerators and functions defined by this extension
+                        with <literal>specData[extName].enums/funcs</literal>. These are not named
+                        of enumerators and functions; they're the actual part of the
+                            <literal>specData</literal> that defines everything about that
+                        enum/func.</para>
+                    <para>This parameter is provided by the <literal>ext-iter</literal>,
+                            <literal>core-ext-iter</literal>, and
+                            <literal>core-ext-cull-iter</literal> actions.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>version</glossterm>
+                <glossdef>
+                    <para>A <emphasis>string</emphasis> (remember this) that contains the version of
+                        interest. Since it's a string, you need to apply <literal>tonumber</literal>
+                        to it to get a proper number.</para>
+                    <para>This parameter is provided by the <literal>version-iter</literal>
+                        action.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>sub_version</glossterm>
+                <glossdef>
+                    <para>A <emphasis>string</emphasis> (remember this) that contains a version
+                        between the first version and the current <literal>version</literal>
+                        version.</para>
+                    <para>This parameter is provided by the <literal>sub-version-iter</literal>
+                        action.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>enum</glossterm>
+                <glossdef>
+                    <para>This is an enumeration. Not the <emphasis>name</emphasis> of an
+                        enumeration; the enumeration itself. It contains the name
+                            <literal>enum.name</literal>, but it also contains versioning
+                        information and so forth. It is an entry from the
+                            <literal>specData.enumerations</literal> table.</para>
+                    <para>This parameter is provided by the <literal>enum-iter</literal>
+                        action.</para>
+                    <para>If you want to get the value of an enumerator, you cannot simply use
+                            <literal>enum.value</literal>. You need the <literal>enum</literal> and
+                        the <literal>enumTable</literal> (see below). Then, you use
+                            <literal>common.ResolveEnumValue</literal>, where
+                            <literal>common</literal> is the <literal>CommonStyle</literal> module
+                        table.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>enumTable</glossterm>
+                <glossdef>
+                    <para>A table of <literal>enum</literal>s, indexed by enumeration name. It comes
+                        from <literal>specData.enumtable</literal>.</para>
+                    <para>This parameter is provided by the <literal>enum-iter</literal>
+                        action.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>func</glossterm>
+                <glossdef>
+                    <para>This is a function. As with <literal>enum</literal>, it is not merely the
+                        name of a function (that's <literal>func.name</literal>); it is the function
+                        itself. It is an element taken from the
+                            <literal>specData.funcData.functions</literal> array. It contains many
+                        properties of a function.</para>
+                    <para>This parameter is provided by the <literal>func-iter</literal>
+                        action.</para>
+                    <para>If you want to get the parameters (C-style) in a function, you can use
+                            <literal>common.GetFuncParamList</literal>, which requires a
+                            <literal>typename</literal> (see below). Otherwise, you would have to
+                        deal with the many difficulties of pulling a viable parameter list from a
+                            <literal>func</literal>.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>typemap</glossterm>
+                <glossdef>
+                    <para>This is a mapping between types as defined in <literal>func</literal> (for
+                        parameters and values) and types as defined by C/C++, as well as the
+                        standard OpenGL/system typedefs and such. It is from
+                            <literal>specData.typemap</literal>.</para>
+                    <para>This parameter is provided by the <literal>func-iter</literal>
+                        action.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>enumSeen</glossterm>
+                <glossdef>
+                    <para>A table indexed by enumerator name. If an entry is present, then the
+                        enumerator was already seen at least once before.</para>
+                    <para>This parameter is provided by the <literal>func-seen</literal>
+                        action.</para>
+                </glossdef>
+            </glossentry>
+            <glossentry>
+                <glossterm>funcSeen</glossterm>
+                <glossdef>
+                    <para>A table indexed by function name. If an entry is present, then the
+                        function was already seen at least once before.</para>
+                    <para>This parameter is provided by the <literal>func-seen</literal>
+                        action.</para>
+                </glossdef>
+            </glossentry>
+        </glosslist>
+    </section>
+</article>

docs/Style_Creation.xml

             <emphasis>share</emphasis> the same structure. <literal>pointer_c</literal> and
             <literal>pointer_cpp</literal> both use the style defined in
             <literal>StyleCommon</literal>, even though they do very different things.</para>
-    <para/>
-    <para/>
-    <para>You should not need to keep state between function invocations (the
-            <literal>pointer_c</literal> style works completely statelessly, relying only on
-        function arguments). However, if you need state, you can create it by using the
-            <literal>Create</literal> function to associate actual state with each instance. The
-        system guarantees that the particular table returned by your style's
-            <literal>Create</literal> function will only be used to generate a single header/source
-        pair.</para>
-    <para>The <literal>style</literal> table will need two sub-tables named
-            <literal>source</literal> and <literal>header</literal>. They contain functions for
-        generating material for source and header files, respectively. Most of the functions are in
-        these two sub-tables.</para>
+    <para>For example, let's say you have part of a code generation system, where you need to
+        iterate over each extension and create a function for it. In that function, you iterate over
+        all of the function pointers within that extension, writing loading code for each one. The
+        part of the structure that provides this would look like this:</para>
+    <programlisting>{ type="ext-iter",
+  { type="block", name="ExtensionFunctionDef(hFile, extName, spec, options),
+    { type="func-iter",
+      { type="write", name="LoadFunctionPtr(hFile, func, typemap, spec, options)", },
+    },
+  },
+},</programlisting>
+    <para>The first section has an <literal>ext-iter</literal>, which iterates all of the extensions
+        the user asked for. It will perform all of the contents once for each extension. Within that
+        is a user-written <literal>block</literal> that defines the beginning and end of the
+        function. Inside of the block is a <literal>func-iter</literal>, which iterates over all of
+        the functions inside of the current extension. So it's like a nested for-loop. Inside of the
+        function iterator is a <literal>write</literal> statement that writes something for each
+        function.</para>
+    <para>The stuff in the <literal>name</literal> tags represent (part of) the name of functions
+        stored within the <emphasis>style</emphasis>. Exactly how this is interpreted depends on the
+        particular statement. For example, the <literal>write</literal> statement above will call a
+        function named <literal><emphasis>Write</emphasis>LoadFunctionPtr</literal>, because the
+        write statement always appends <literal>Write</literal> to its statements.</para>
+    <para>The <literal>block</literal> statement is a bit more complex, as it will call two separate
+        functions: <literal>WriteBlockBeginExtensionFunctionDef</literal> and
+            <literal>WriteBlockEndExtensionFunctionDef</literal>. It calls the first one before
+        executing any of its containing statements, and it calls the second after executing its
+        contents. Thus the block's contents are bound.</para>
+    <para>The style should have functions with the appropriate names; if it does not, a runtime
+        error will occur, providing information that the function name couldn't be called.</para>
+    <para>The parameter list is actually quite special. Each parameter name has a very specific
+        meaning and stores very specific data (which you must <emphasis>never modify</emphasis>).
+        But different parameters are available at different times. For example,
+            <literal>extName</literal> represents the name of the current extension. But there can
+        only be a <quote>current extension</quote> when you are iterating over a group of
+        extensions. Likewise, <literal>func</literal> is a function loaded from the appropriate spec
+        file, but it is only available while iterating over a set of functions.</para>
+    <para>As with function names, if a parameter is specified in a place where it is not made
+        available (such as providing <literal>func</literal> to
+            <literal>ExtensionFunctionDef</literal>), a runtime error explaining the problem will
+        occur.</para>
+    <para>This is a simple overview of the process. There is a rather lot more complexity than
+        that.</para>
+    <para>In general, a style and a structure are created in tandem; if a structure is to be used in
+        multiple styles, then the structure can be created first. But it's much easier to make part
+        of a structure, implement enough style functions to use it, then expand on it.</para>
     <para><phrase role="toc"/></para>
     <section>
-        <title>Naming convention</title>
-        <para>The system follows a strict naming convention for its parameters. Each name refers to
-            an object or value with specific data. Here are the possibilities:</para>
-        <glosslist>
-            <glossentry>
-                <glossterm>options</glossterm>
-                <glossdef>
-                    <para>The options data structure. It contains the options processed from the
-                        command-line. Among these is <literal>extensions</literal>, the list of
-                        extension names that are being explicitly written. You can tell which spec
-                        is being used with <literal>options.spec</literal>, but it's better to rely
-                        on the <literal>spec</literal> parameter as seen below.</para>
-                </glossdef>
-            </glossentry>
-            <glossentry>
-                <glossterm>hFile</glossterm>
-                <glossdef>
-                    <para>A <literal>TabbedFile</literal>. This is a special kind of Lua IO file. It
-                        supports all of the Lua IO methods (<emphasis>DO NOT CLOSE IT!</emphasis>),
-                        but it's designed to handle indentation. As such, it extends the Lua IO with
-                        specialized routines to auto-indent individual lines. This allows the system
-                        to determine the indention to use based on command-line options. The
-                        assumption with almost all of the writing functions is that each write is an
-                        individual line.</para>
-                    <para>Note that you must use it with Lua's member calling conventions
-                            (<literal>hFile:write</literal>, for example). If you try to use
-                            <literal>io.write</literal>, things will break.</para>
-                    <para><literal>hFile:inc</literal> and <literal>hFile:dec</literal> are
-                        functions that increment/decrement the current indention level. The
-                        indention can be preserved with <literal>hFile:push</literal> and restored
-                        with <literal>hFile:pop</literal>.</para>
-                    <para>The <literal>TabbedFile</literal> also offers the ability to do string
-                        formatting directly into the write. <literal>hFile:fmt</literal> takes a
-                        format string and some parameters, forwards the parameters to
-                            <literal>string.format</literal>, then writes that string as a
-                        line.</para>
-                    <para>There are block writing functions, <literal>hFile:writeblock</literal> and
-                            <literal>hFile:fmtblock</literal>. These functions will split the
-                        written string into individual lines and indent each one.</para>
-                    <para>If you don't want indented writes, then use
-                            <literal>hFile:rawwrite</literal> and
-                        <literal>hFile:rawfmt</literal>.</para>
-                </glossdef>
-            </glossentry>
-            <glossentry>
-                <glossterm>specData</glossterm>
-                <glossdef>
-                    <para>This is the entire data containing every enumeration, typedef, function,
-                        etc for the specification (OpenGL, WGL, GLX). It is a massive struct, and
-                        it's format is complex.</para>
-                    <para>You can see what specData looks like by reading
-                            <filename>glspecs/glspec.lua</filename>. <literal>specData</literal> is
-                        derived from this table, but with some modifications. The modifications are
-                        detailed in the comments at the top of
-                            <filename>modules/LoadLuaSpec.lua</filename>. They're primarily
-                        convenience stuff, to make it easier to find an enum by its enumeration name
-                        and so forth.</para>
-                </glossdef>
-            </glossentry>
-            <glossentry>
-                <glossterm>spec</glossterm>
-                <glossdef>
-                    <para>This is a struct containing functions used to get specification-specific
-                        strings. This allows the style of writing to be mostly independent of things
-                        like whether it is writing to OpenGL or WGL. For example, if you have the
-                        base name of an enumeration, and you want to prefix it with the spec-defined
-                        prefix for enumerations, you do this:</para>
-                    <programlisting>spec.EnumNamePrefix() .. enumName</programlisting>
-                    <para>There are a number of spec functions that return prefix strings or other
-                        spec-based strings. You can find these in the
-                            <filename>modules/Specs.lua</filename> file, with a comment stating what
-                        each one returns.</para>
-                    <para>There are also some functions that provide general information: list of
-                        versions, list of core extensions, a string containing the definitions for
-                        the OpenGL function to load function pointers, etc. These lists are all
-                        stored in the <filename>data</filename> directory, using the file format
-                            <literal>data/&lt;specName>_spec&lt;data>.lua</literal>. </para>
-                </glossdef>
-            </glossentry>
-            <glossentry>
-                <glossterm>extName</glossterm>
-                <glossdef>
-                    <para>The base name of an extension. Usually paired with
-                            <literal>specData</literal>, as the name alone isn't terribly useful.
-                        You can get the list of enumerators and functions defined by this extension
-                        with <literal>specData[extName].enums/funcs</literal>. These are not named
-                        of enumerators and functions; they're the actual part of the
-                            <literal>specData</literal> that defines everything about that
-                        enum/func.</para>
-                </glossdef>
-            </glossentry>
-            <glossentry>
-                <glossterm>enum</glossterm>
-                <glossdef>
-                    <para>This is an enumeration. Not the <emphasis>name</emphasis> of an
-                        enumeration; the enumeration itself. It contains the name
-                            <literal>enum.name</literal>, but it also contains versioning
-                        information and so forth. It is an entry from the
-                            <literal>specData.enumerations</literal> table.</para>
-                    <para>If you want to get the value of an enumerator, you cannot simply use
-                            <literal>enum.value</literal>. You need the <literal>enum</literal> and
-                        the <literal>enumTable</literal> (see below). Then, you use
-                            <literal>common.ResolveEnumValue</literal>, where
-                            <literal>common</literal> is the <literal>CommonStyle</literal> module
-                        table.</para>
-                </glossdef>
-            </glossentry>
-            <glossentry>
-                <glossterm>enumTable</glossterm>
-                <glossdef>
-                    <para>A table of <literal>enum</literal>s, indexed by enumeration name. It comes
-                        from <literal>specData.enumtable</literal>.</para>
-                </glossdef>
-            </glossentry>
-            <glossentry>
-                <glossterm>func</glossterm>
-                <glossdef>
-                    <para>This is a function. As with <literal>enum</literal>, it is not merely the
-                        name of a function (that's <literal>func.name</literal>); it is the function
-                        itself. It is an element taken from the
-                            <literal>specData.funcData.functions</literal> array. It contains many
-                        properties of a function.</para>
-                    <para>If you want to get the parameters (C-style) in a function, you can use
-                            <literal>common.GetFuncParamList</literal>, which requires a
-                            <literal>typename</literal> (see below). Otherwise, you would have to
-                        deal with the many difficulties of pulling a viable parameter list from a
-                            <literal>func</literal>.</para>
-                </glossdef>
-            </glossentry>
-            <glossentry>
-                <glossterm>typemap</glossterm>
-                <glossdef>
-                    <para>This is a mapping between types as defined in <literal>func</literal> (for
-                        parameters and values) and types as defined by C/C++, as well as the
-                        standard OpenGL/system typedefs and such. It is from
-                            <literal>specData.typemap</literal>.</para>
-                </glossdef>
-            </glossentry>
-            <glossentry>
-                <glossterm>version</glossterm>
-                <glossdef>
-                    <para>A <emphasis>string</emphasis> (remember this) that contains the version of
-                        interest. Since it's a string, you need to apply <literal>tonumber</literal>
-                        to it to get a proper number.</para>
-                </glossdef>
-            </glossentry>
-        </glosslist>
+        <title>Making the Structure</title>
+        <para>This page will provide a basic overview for making a simple structure. <link
+                xlink:href="Structure_Reference">The reference page</link> has more in-depth
+            documentation about all aspects of structure creation.</para>
+        <para/>
+        <para/>
     </section>
     <section>
         <title>Library functions</title>
             spec's prefix.</para>
     </section>
     <section>
-        <title>File structure</title>
-        <para>A good way to understand the nature of the functions is to show how the functions will
-            be called by the system to build the header/source file. Here is the structure of a
-            header file, as far as the system is concerned. Each function call represents the system
-            calling that function with those parameters one or more times.</para>
-        <programlisting>header.CreateFile(basename, options) //Return the name of the file.
-
-header.WriteBeginIncludeGuard(hFile, spec, options)
-  header.WriteStdTypedefs(hFile, specData, spec, options)
-  header.WriteSpecTypedefs(hFile, specData, spec, options)
-
-
-  header.WriteBeginDecl(hFile, spec, options)
-
-    header.WriteBeginExtVarDeclBlock(hFile, spec, options)
-      //For each user-specified extension
-      header.WriteExtVariableDecl(hFile, extName, specData, spec, options)
-      header.WriteExtVariableDecl(hFile, ..., specData, spec, options)
-      ...
-    header.WriteEndExtVarDeclBlock(hFile, spec, options)
-
-    header.WriteBeginEnumDeclBlock(hFile, spec, options)
-      //For each enum to be written, in order of extensions/core
-      //Will call one or the other.
-      header.WriteEnumDecl(hFile, enum, enumTable, spec, options)
-      header.WriteEnumPrevDecl(hFile, enum, enumTable, spec, options, extName)
-    header.WriteEndEnumDeclBlock(hFile, spec, options)
-
-
-    header.WriteBeginFuncDeclBlock(hFile, spec, options)
-      //For each user-specified extension:
-      header.WriteBeginExtFuncDeclBlock(hFile, extName, spec, options)
-        //For each function in that extension
-        header.WriteFuncDecl(hFile, func, typemap, spec, options)
-        header.WriteFuncDecl(hFile, ..., typemap, spec, options)
-        ...
-      header.WriteEndExtFuncDeclBlock(hFile, extName, spec, options)
-      
-      //For each version, where applicable:
-        //For each core extension that was not user-specified:
-        header.WriteBeginExtFuncDeclBlock(hFile, extName, spec, options)
-          header.WriteFuncDecl(hFile, func, typemap, spec, options)
-          header.WriteFuncDecl(hFile, ..., typemap, spec, options)
-          ...
-        header.WriteEndExtFuncDeclBlock(hFile, extName, spec, options)
-
-        //For each core function from this version *not* in a core extension.
-        header.WriteFuncDecl(hFile, func, typemap, spec, options)
-        header.WriteFuncDecl(hFile, ..., typemap, spec, options)
-        ...
-    header.WriteEndFuncDeclBlock(hFile, spec, options)
-    
-    header.WriteBeginSysDeclBlock(hFile, spec, options)
-      header.WriteUtilityDecls(hFile, spec, options)
-      header.WriteMainLoaderFuncDecl(hFile, spec, options)
-      header.WriteVersioningFuncDecls(hFile, spec, options) //Only if the spec has versions.
-    header.WriteEndSysDeclBlock(hFile, spec, options)
-
-  header.WriteEndDecl(hFile, spec, options)
-  
-header.WriteEndIncludeGuard(hFile, spec, options)</programlisting>
-        <para>And here is the equivalent structure for the source files:</para>
-        <programlisting>source.CreateFile(basename, options) //Name of the file.
-
-source.WriteIncludes(hFile, spec, options)
-#include "HEADER_FILENAME"
-
-//Function pointer loader func from spec.loaderFunc()
-
-source.WriteBeginDef(hFile, spec, options)
-
-  source.WriteBeginExtVarDefBlock(hFile, spec, options)
-    //For each user-specified extension
-    source.WriteExtVariableDef(hFile, extName, specData, spec, options)
-    source.WriteExtVariableDef(hFile, ..., specData, spec, options)
-    ...
-  source.WriteEndExtVarDefBlock(hFile, spec, options)
-  
-  //For each user-specified extension:
-  source.WriteBeginExtFuncDefBlock(hFile, extName, spec, options)
-    //For each function in the extension:
-    source.WriteFuncDef(hFile, func, typemap, spec, options)
-    source.WriteFuncDef(hFile, ..., typemap, spec, options)
-    ...
-    
-    source.WriteBeginExtLoaderBlock(hFile, extName, spec, options)
-      //For each function in the extension
-      source.WriteCoreFuncLoader(hFile, func, typemap, spec, options)
-    source.WriteEndExtLoaderBlock(hFile, extName, spec, options)
-  source.WriteEndExtFuncDefBlock(hFile, extName, spec, options)
-  
-  source.WriteBeginCoreFuncDefBlock(hFile, version, spec, options)
-    //For each version, where applicable
-      //For each core extension in that version which was not user-specified
-      source.WriteBeginExtFuncDefBlock(hFile, extName, spec, options)
-        //For each function in that core extension:
-        source.WriteCoreFuncLoader(hFile, func, typemap, spec, options)
-        source.WriteCoreFuncLoader(hFile, .., typemap, spec, options)
-        ...
-      source.WriteEndExtFuncDefBlock(hFile, extName, spec, options)
-      
-      //For each function from that version not in a core extension:
-      source.WriteCoreFuncLoader(hFile, func, typemap, spec, options)
-      source.WriteCoreFuncLoader(hFile, .., typemap, spec, options)
-      ...
-
-    source.WriteBeginCoreLoaderBlock(hFile, version, spec, options)
-      //For each version, where applicable
-        //For each core extension in that version which was not user-specified
-        {
-          //For each function in that core extension:
-          source.WriteCoreFuncLoader(hFile, func, typemap, spec, options)
-        }
-          
-        //For each function from that version *not* in a core extension:
-        source.WriteCoreFuncLoader(hFile, func, typemap, spec, options)
-    source.WriteEndCoreLoaderBlock(hFile, version, spec, options)
-  source.WriteEndCoreFuncDefBlock(hFile, version, spec, options)
-  
-
-  source.WriteBeginSysDefBlock(hFile, spec, options)
-    source.WriteUtilityDefs(hFile, specData, spec, options)
-    source.WriteMainLoaderFunc(hFile, specData, spec, options)
-    source.WriteVersioningFuncs(hFile, specData, spec, options) //Only if the spec has versions.
-  source.WriteEndSysDefBlock(hFile, spec, options)
-
-source.WriteEndDef(hFile, spec, options)</programlisting>
-    </section>
-    <section>
         <title>Style function reference</title>
         <para>The file <filename>modules/SampleStyle.lua</filename> contains a file that you can
             simply copy and paste to start making a style. Every function you need to define is

docs/Style_Pointer_CPP.xml

             <para>Certain enumerators use widely used by OS's for various things. Windows for
                 example <literal>#define</literal>s <literal>TRUE</literal> and
                     <literal>FALSE</literal>, among others. There's no automated way to detect this,
-                so there's just a list of the known ones. These known enumerators will be suffixed
-                with an <quote><literal>_</literal></quote> character. So <literal>TRUE</literal>
-                becomes <literal>TRUE_</literal>.</para>
+                so there's just a list of the known ones. The C++ standard states that all
+                identifiers that begin with an underscore followed by a capital letter are reserved
+                for the standard library. So we cannot prefix them with an underscore; instead, we
+                suffix them with one. So <literal>TRUE</literal> becomes
+                <literal>TRUE_</literal>.</para>
         </listitem>
     </orderedlist>
     <para>The functions are function pointers, but their names are not hidden behind a

docs/ToCreole.xsl

 </xsl:text>
     </xsl:template>
     
+    <xsl:template match="db:glossterm" mode="file">
+        <xsl:text>**</xsl:text>
+        <xsl:apply-templates select="*|text()" mode="#current"/>
+        <xsl:text>**</xsl:text>
+    </xsl:template>
     <!--
     <xsl:template match="db:footnote" mode="file">
         <xsl:text>[[hottip:</xsl:text>

modules/SampleStyle.lua

 -- Style retrieval machinery
 
 local function Create()
-	return common.DeepCopyTable(my_style)
+	return common.DeepCopyTable(my_style), common.GetStandardStructure()
 end
 
 return { Create = Create }