Commits

Jason McKesson committed 940f213

Some regularization of the code generation system.
Improved creole exporting and docs.

Comments (0)

Files changed (9)

docs/Load Docs.xpr

                                     <String xml:space="preserve">XSL</String>
                                 </field>
                                 <field name="url">
-                                    <String xml:space="preserve">Common_Extension_Files.xml</String>
+                                    <String xml:space="preserve">Style_Creation.xml</String>
                                 </field>
                             </scenarioAssociation>
                             <scenarioAssociation>
                                     <String xml:space="preserve">XSL</String>
                                 </field>
                                 <field name="url">
-                                    <String xml:space="preserve">Extension_Files.xml</String>
-                                </field>
-                            </scenarioAssociation>
-                            <scenarioAssociation>
-                                <field name="name">
-                                    <String xml:space="preserve">ToCreole</String>
-                                </field>
-                                <field name="type">
-                                    <String xml:space="preserve">XSL</String>
-                                </field>
-                                <field name="url">
                                     <String xml:space="preserve">Styles.xml</String>
                                 </field>
                             </scenarioAssociation>
                                     <String xml:space="preserve">XSL</String>
                                 </field>
                                 <field name="url">
-                                    <String xml:space="preserve">Style_Creation.xml</String>
-                                </field>
-                            </scenarioAssociation>
-                            <scenarioAssociation>
-                                <field name="name">
-                                    <String xml:space="preserve">ToCreole</String>
-                                </field>
-                                <field name="type">
-                                    <String xml:space="preserve">XSL</String>
-                                </field>
-                                <field name="url">
-                                    <String xml:space="preserve">Command_Line_Options.xml</String>
+                                    <String xml:space="preserve">Style_Pointer_C.xml</String>
                                 </field>
                             </scenarioAssociation>
                             <scenarioAssociation>
                                     <String xml:space="preserve">XSL</String>
                                 </field>
                                 <field name="url">
-                                    <String xml:space="preserve">Style_Pointer_C.xml</String>
+                                    <String xml:space="preserve">Extension_Files.xml</String>
+                                </field>
+                            </scenarioAssociation>
+                            <scenarioAssociation>
+                                <field name="name">
+                                    <String xml:space="preserve">ToCreole</String>
+                                </field>
+                                <field name="type">
+                                    <String xml:space="preserve">XSL</String>
+                                </field>
+                                <field name="url">
+                                    <String xml:space="preserve">Common_Extension_Files.xml</String>
+                                </field>
+                            </scenarioAssociation>
+                            <scenarioAssociation>
+                                <field name="name">
+                                    <String xml:space="preserve">ToCreole</String>
+                                </field>
+                                <field name="type">
+                                    <String xml:space="preserve">XSL</String>
+                                </field>
+                                <field name="url">
+                                    <String xml:space="preserve">Command_Line_Options.xml</String>
                                 </field>
                             </scenarioAssociation>
                             <scenarioAssociation>

docs/Style_Creation.xml

     <title>Style Creation</title>
     <para>The style system is designed to be extensible and as simple as possible. That doesn't mean
         it's not somewhat complex.</para>
+    <para>A <literal>style</literal> is a Lua table that contains a number of functions and tables.
+        These functions will be called by the system to do specific things at specific times.</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, you can use local variables to store state if you wish. The
+        system will never ask your style to run twice (at least, not without a process
+        restart).</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><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>
+    </section>
+    <section>
+        <title>Library functions</title>
+        <para>There are a number of common operations that different styles will share. The
+                <literal>CommonStyle</literal> module returns a table containing these operations.
+            They are defined as follows:</para>
+    </section>
+    <section>
+        <title>Resolving conflicts</title>
+        <para>Your style may create global definitions and so forth that come into conflict with
+            other things. Here are the rules you need to follow:</para>
+        <itemizedlist>
+            <listitem>
+                <para>The user should be able to use different specs with the same style and link
+                    them together in the same program without conflicts. Files generated like this
+                    should coexist. This effectively means that you need to make sure that your
+                    names are prefixed with something spec-specific. The <literal>spec</literal>
+                    table has functions to get an appropriate prefix; the
+                        <literal>spec.DeclPrefix</literal> is the general prefix for
+                    declaration/definitions of things that can conflict at link time.</para>
+            </listitem>
+            <listitem>
+                <para>The user should be able to #include the standard headers for OpenGL/GLX/WGL
+                        <emphasis>after</emphasis> your generated header without incident. So you
+                    need to #define various values to prevent the inclusion of standard headers (or
+                    include them yourself).</para>
+            </listitem>
+            <listitem>
+                <para>If the user tries to #include the standard spec headers
+                        <emphasis>before</emphasis> your generated header, you should provide an
+                    appropriate compile-time error. So you need to test to see if standard variables
+                    are included, and fail with a <literal>#error</literal> if they are.</para>
+            </listitem>
+            <listitem>
+                <para>The user should be able to supply a prefix with the <literal>-prefix</literal>
+                    option. The user should be able to generate two separate source/header files
+                    with the <emphasis>exact same options</emphasis> with the exception of the
+                    prefixes. That is, the user can supply the same specification, version,
+                    extensions list, etc. And both files should be able to be linked together into a
+                    single program entirely without incident. Both loaders should be able to
+                    co-exist peacefully; loading function pointers for one should not impact the
+                    loading of function pointers for another</para>
+                <para>Note: if your style does static linking, such as for Linux or OSX, then the
+                    part about loading pointers for one not impacting the other can be
+                    ignored.</para>
+                <para>This rule effectively means that you must prefix every non-static definition.
+                    Namespace scoping would also work, if you use the prefix as the namespace (or
+                    prefix the namespace with it).</para>
+                <para>The prefix string is in <literal>options.prefix</literal>. Note that it will
+                    always be present; if you want to test for a user-defined prefix, test it
+                    against the empty string.</para>
+            </listitem>
+        </itemizedlist>
+        <para>So prefix names that can conflict with the user-prefix <emphasis>and</emphasis> the
+            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)
+
+    //For each user-specified extension
+    header.WriteExtVariableDecl(hFile, extName, specData, spec, options)
+    header.WriteExtVariableDecl(hFile, ..., specData, 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.WriteBeginFuncDeclBlock(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.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"
+
+source.WriteBeginDef(hFile, spec, options)
+
+  //For each user-specified extension
+  source.WriteExtVariableDef(hFile, extName, specData, spec, options)
+  source.WriteExtVariableDef(hFile, ..., specData, 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.WriteUtilityDefs(hFile, specData, spec, options)
+  source.WriteMainLoaderFunc(hFile, specData, spec, options)
+  source.WriteVersioningFuncs(hFile, specData, spec, options) //Only if the spec has versions.
+
+source.WriteEndDef(hFile, spec, options)</programlisting>
+    </section>
+    <section>
+        <title>Style function reference</title>
+        <para>The reference documentation for style functions is available here.</para>
+    </section>
 </article>

docs/Style_Pointer_C.xml

         function pointers accounted for). Otherwise, some number of function pointers failed to
         load. To get the number of functions that failed to load for the extension, take the integer
         value and subtract <literal>LOAD_SUCCEEDED</literal> from it.</para>
-    <para>The return value for the function loader works the same way. It refers to the success or
-        failure to load the core functions (obviously for WGL/GLX, there are no core functions, so
-        it will always be successful). The attempt will always be made to load the core functions,
-        so <literal>LOAD_FAILED</literal> is not a possibility.</para>
-    <para>Also, this style will generate functions to query version availability for core OpenGL. </para>
+    <para>The return value for the function loader works mostly the same way.
+            <literal>LOAD_FAILED</literal> does not signal the failure to load the core functions or
+        some extensions. It signals the failure of the process to work <emphasis>at all.</emphasis>
+        This is for something very basic, like the failure to get the function pointers needed to
+        get the extension string. Without the extension string, we cannot detect what should and
+        shouldn't be loaded. Therefore, if this is returned, <emphasis>nothing</emphasis> was
+        loaded.</para>
+    <para>For non-fail states, the value works like for the individual extension variables, except
+        that the number that failed to load refer to core functions. So for specs that don't load
+        core functions, it will always return <literal>LOAD_SUCCEEDED</literal>.</para>
+    <para>Also, this style will generate functions to query the version of the OpenGL
+        context.</para>
     <section>
         <title>Compatibility</title>
         <para>This style is intended to be maximally compatible with regular OpenGL programs. You

docs/ToCreole.xsl

     </xsl:template>
     
     <xsl:template match="db:programlisting" mode="file">
-        <xsl:text>{{{</xsl:text>
+        <xsl:text>{{{
+</xsl:text>
         <xsl:apply-templates select="*|text()" mode="#current"/>
-        <xsl:text>}}}
+        <xsl:text>
+}}}
 
 </xsl:text>
     </xsl:template>
         <xsl:text>**//</xsl:text>
     </xsl:template>
     
+    <xsl:template match="db:phrase[@role='toc']" mode="file">
+        <xsl:text><![CDATA[<<toc>>]]></xsl:text>
+    </xsl:template>
+    
     <xsl:template match="db:citetitle" mode="file">
         <xsl:text>//**</xsl:text>
         <xsl:apply-templates select="*|text()" mode="#current"/>
             <xsl:text> </xsl:text>
         </xsl:if>
     </xsl:template>
+
+    <xsl:template match="text()[ancestor::db:programlisting]" mode="file">
+        <xsl:value-of select="."/>
+    </xsl:template>
     
     <xsl:template match="db:title" mode="file"/>
 </xsl:transform>

modules/CommonStyle.lua

 	return TabbedFile.TabbedFile(hFile, indent)
 end
 
+--Retrieves the common typedefs used by OpenGL 1.1.
 function common.GetStdTypedefs()
 	return dofile(util.GetDataFilePath() .. "style_commontypedefs.lua")
 end
 
+--Writes passthru data from the specData, with proper indentation.
 function common.WritePassthruData(hFile, strArray)
 	for _, str in ipairs(strArray) do
 		--unindent after #endif
 	hFile:write("\n")
 end
 
+--Determines the value of the enumeration.
 local function ResolveEnumValue(enum, enumTable)
 	if(enum.copy) then
 		return common.ResolveEnumValue(enumTable[enum.value], enumTable),
 end
 common.ResolveEnumValue = ResolveEnumValue
 
+--Gets the return type for a function.
 function common.GetFuncReturnType(func, typemap)
 	return typemap[func["return"]] or func["return"]
 end

modules/Generate.lua

 	local hFile, filename = header.CreateFile(basename, options)
 	
 	--Start include-guards.
-	--IGs are built from style and spec data. The spec provides a string that
-	--the style uses in constructing it.
-	local inclGuard =
-		header.MakeIncludeGuard(options.prefix, spec.GetIncludeGuardString())
-	
-	hFile:fmt("#ifndef %s\n", inclGuard)
-	hFile:fmt("#define %s\n", inclGuard)
+	header.WriteBeginIncludeGuard(hFile, spec, options)
 	hFile:write("\n")
 	
 	--Spec-specific initialization comes next. Generally macros and #includes.
 	
 	--Write the function loading stuff.
 	style.WriteLargeHeading(hFile, "Loading Functions")
-	header.WriteStatusCodeDecl(hFile, spec, options)
+	header.WriteUtilityDecls(hFile, spec, options)
 	hFile:write("\n")
 	header.WriteMainLoaderFuncDecl(hFile, spec, options)
 	if(options.version) then
 	header.WriteEndDecl(hFile, spec, options)
 	
 	--Ending includeguard.
-	hFile:fmt("#endif //%s\n", inclGuard)
+	header.WriteEndIncludeGuard(hFile, spec, options)
+	hFile:write("\n")
 	hFile:close()
 	
 	return filename
 		for _, version in ipairs(spec.GetVersions()) do
 			if(tonumber(version) <= tonumber(options.version)) then
 				if(coreExts[version]) then
+					source.WriteBeginExtFuncDefBlock(hFile, extName, spec, options)
+
 					for _, extName in ipairs(coreExts[version]) do
 						WriteCoreFuncLoaderFromList(hFile,
 							specData.extdefs[extName].funcs,
 							options, spec, style, specData)
 					end
+					
+					source.WriteEndExtFuncDefBlock(hFile, extName, spec, options)
+
 				end
 				
 				--Write the actual core functions, if any.
 	hFile:write "\n"
 	
 	--Write any additional functions that load other things.
-	source.WriteVersioningFuncs(hFile, specData, spec, options)
-	hFile:write "\n"
+   	if(options.version) then
+        source.WriteVersioningFuncs(hFile, specData, spec, options)
+        hFile:write "\n"
+	end
 
 	--Write any definitions scoping end.
 	source.WriteEndDef(hFile, spec, options)

modules/StylePointerC.lua

 	return common.CreateFile(filename, options.indent), filename
 end
 
-function my_style.header.MakeIncludeGuard(prefix, specIncl)
-	local str = "POINTER_C_GENERATED_HEADER_" .. specIncl .. "_H"
-	if(#prefix > 0) then
-		return prefix:upper() .. "_" .. str
+
+local function GetIncludeGuard(hFile, spec, options)
+	local str = "POINTER_C_GENERATED_HEADER_" ..
+		spec.GetIncludeGuardString() .. "_H"
+
+	if(#options.prefix > 0) then
+		return options.prefix:upper() .. "_" .. str
 	end
 	
 	return str
 end
 
+function my_style.header.WriteBeginIncludeGuard(hFile, spec, options)
+	local inclGuard = GetIncludeGuard(hFile, spec, options)
+	
+	hFile:fmt("#ifndef %s\n", inclGuard)
+	hFile:fmt("#define %s\n", inclGuard)
+end
+
+function my_style.header.WriteEndIncludeGuard(hFile, spec, options)
+	local inclGuard = GetIncludeGuard(hFile, spec, options)
+	
+	hFile:fmt("#endif //%s\n", inclGuard)
+end
+
 function my_style.header.WriteStdTypedefs(hFile, specData, options)
 	local defArray = common.GetStdTypedefs()
 	
 	return string.format("%s%s%s", options.prefix, spec.DeclPrefix(), name)
 end
 
-function my_style.header.WriteStatusCodeDecl(hFile, spec, options)
+function my_style.header.WriteUtilityDecls(hFile, spec, options)
 	hFile:fmt("enum %s\n", GetStatusCodeEnumName(spec, options))
 	hFile:write("{\n")
 	hFile:inc()
 		hFile:write(GetStatusCodeName("LOAD_FAILED", spec, options), " = 0,\n")
 		hFile:write(GetStatusCodeName("LOAD_SUCCEEDED", spec, options), " = 1,\n")
---		hFile:write(GetStatusCodeName("LOAD_PARTIAL", spec, options), " = 2,\n")
 	hFile:dec()
 	hFile:write("};\n")
 end
 function my_style.source.WriteBeginDef(hFile, spec, options) end
 function my_style.source.WriteEndDef(hFile, spec, options) end
 
-function my_style.source.WriteExtVariableDef(hFile, ext, specData, spec, options)
-	hFile:fmt("int %s = %s;\n", GetExtVariableName(ext, spec, options),
+function my_style.source.WriteExtVariableDef(hFile, extName, specData, spec, options)
+	hFile:fmt("int %s = %s;\n", GetExtVariableName(extName, spec, options),
 		GetStatusCodeName("LOAD_FAILED", spec, options));
 end
 

modules/Styles.lua

 - header.CreateFile(basename, options)
 --		basename is the filename sans extension. It opens a TabbedFile from it, using the options in options. It returns two values: a TabbedFile, and the actual filename used.
 
-- header.MakeIncludeGuard(prefix, specIncl)
---		specIncl is an include-guard string from the spec. It returns a string that includes the two strings, which is appropriate for use as an include-guard.
+- header.WriteBeginIncludeGuard(hFile, spec, options)
+--		Writes the opening include-guard, if any.
+
+- header.WriteEndIncludeGuard(hFile, spec, options)
+--		Ends the opening include-guard, if any.
 
 - header.WriteStdTypedefs(hFile, specData, spec, options)
 --		Writes the standard typedefs.
 - header.WriteFuncDecl(hFile, func, typemap, spec, options)
 --	Writes a function declaration. This can include multiple statements, such as a typedef, an extern function pointer declaration, and a #define or whatever.
 
-- header.WriteStatusCodeDecl(hFile, spec, options)
---	Writes any declarations for status codes as returned from the loader and so forth.
+- header.WriteUtilityDecls(hFile, spec, options)
+--	Writes any declarations needed for utility bits, like status codes of return values, etc.
 
 - header.WriteMainLoaderFuncDecl(hFile, spec, options)
 --	Writes the declaration for the main loading function.
 - source.WriteEndDef(hFile, spec, options)
 --	Ends any scoping for the block of definitions.
 
-- source.WriteExtVariableDef(hFile, ext, specData, spec, options)
---	Writes the extension variable definition for `ext`.
+- source.WriteExtVariableDef(hFile, extName, specData, spec, options)
+--	Writes the extension variable definition for `extName`.
 
 - source.WriteBeginExtFuncDefBlock(hFile, extName, spec, options)
 --	Writes the beginning of an extension's block that contains function pointer definitions and the loader function for this extension.

modules/TabbedFile.lua

 - dec: Decrements the tab count by the number given, or by 1 if nothing is given.
 - push: Preserves the current tab count.
 - pop: Restores the previously preserved tab count.
-- fmt: As string.format followed by an indented write
 - write: An indented write; everything is written after the indent.
 - writeblock: Takes a single string, breaks it down into multiple lines, and writes each line indented.
+- fmt: As string.format followed by an indented write
 - fmtblock: As string.format, followed by calling `writeblock`.
 - rawfmt: As string.format followed by a NON-indented write.
 - rawwrite: hFile:write.