Commits

Jason McKesson committed 3c065bc

Some documentation and a start at the Creole exporter.

Comments (0)

Files changed (5)

docs/Command Line Options.xml

         or less like the standard command-line options for typical Linux/Windows programs. Options
         that have a single value can take their parameters as either
             <literal>-opt_name=parameter</literal> or <literal>-opt_name parameter</literal>.</para>
-    <para>You must specify an output filename, which will be used as the base filename for
-        generating the output. It can have arbitrary path information, but it should not have an
-        extension. The generated files will take the base filename and append an appropriate suffix
-        and extension to it. You can give the system the same basename for the different
-        specifications (WGL, GLX, OpenGL) without issue.</para>
+    <para>With Lua on the path, the command-line should be specified as follows:</para>
+    <programlisting>lua pathToLoadgen/LoadGen.lua &lt;output filename> &lt;options></programlisting>
+    <para>The <literal>&lt;output filename></literal> must be specified. The path provided is
+        relative to the current directory. The base filename of the path (everything after the last
+        directory separator) will be decorated as appropriate for generating the output files. You
+        should not provide an extension; the system will provide those as needed. The generated
+        files will append an appropriate prefix, depending on which specifications you are
+        generating (OpenGL, WGL, or GLX), so you can provide the same base filename for all of
+        these.</para>
     <para>The output filename should be specified before any of the options. You can specify it
         after the options or even between options, but if you specify it after the
             <literal>-exts</literal> option (but before any subsequent options), the system will
         <glossentry>
             <glossterm>-prefix</glossterm>
             <glossdef>
-                <para>The code generation system will try to minimize the number of global variables
-                    as much as possible. However, it will have to use some non-static variables for
-                    various things.</para>
-                <para>While each individual specification is guaranteed not to have variable name
-                    collisions, it may be useful to have an application use multiple independent
-                    loaders for the same specification. For example, you could have a GL 2.1 set of
-                    functions and a GL 3.3 set (obviously each file must decide for itself which to
-                    use). Their global variables would conflict, making this unworkable.</para>
+                <para>The code generation system will try to minimize the number of non-static
+                    global variables it defines as much as possible. However, it will have to use
+                    some non-static variables for various things.</para>
+                <para>Code generated from the different specifications are guaranteed not to have
+                    name collisions. However, if you generate code from the
+                        <emphasis>same</emphasis> specification, with different sets of extensions
+                    or versions, collisions will occur.</para>
                 <para>The prefix option allows you to define a string that will be prepended to any
                     non-static (or otherwise hidden) global variables, where possible. As such, the
                     prefix should start with characters that are valid for C/C++ identifiers.</para>
         <glossentry>
             <glossterm>-version</glossterm>
             <glossdef>
-                <para>The highest version of OpenGL to export. You must use this
-                        <emphasis>only</emphasis> when <literal>-spec</literal> is
-                        <literal>gl</literal>. And you must use it when the specification is
-                        <literal>gl</literal>.</para>
+                <para>The highest version of OpenGL to export. You may <emphasis>only</emphasis> use
+                    this when <literal>-spec</literal> is <literal>gl</literal>. And you must use it
+                    when the specification is <literal>gl</literal>.</para>
             </glossdef>
         </glossentry>
         <glossentry>
             <glossterm>-profile</glossterm>
             <glossdef>
-                <para>The OpenGL profile to export. For OpenGL versions that don't have the
-                    core/compatibility distinction, the option is ignored. It must be one of the
-                    following values:</para>
+                <para>The OpenGL profile to export. It must be one of the following values:</para>
                 <itemizedlist>
                     <listitem>
                         <para><literal>core</literal>: default</para>
                     </listitem>
                     <listitem>
-                        <para><literal>compatibility</literal></para>
+                        <para><literal>compatibility</literal>: It is an error to specify this for
+                            OpenGL versions that do not have the core/compatibility
+                            distinction.</para>
                     </listitem>
                 </itemizedlist>
             </glossdef>
                     <listitem>
                         <para><literal>pointer_c</literal>: default.</para>
                     </listitem>
-                    <listitem>
-                        <para><literal>pointer_cpp</literal></para>
-                    </listitem>
                 </itemizedlist>
                 <para>The specific meaning of these parameters is explained elsewhere. Note that the
-                    system is extensible; new styles can be added by modifying an appropriate script
-                    and hooking it into the right place in <filename>_Styles.lua</filename>.</para>
+                    system is designed to be extensible; new styles can be added by modifying an
+                    appropriate script and hooking it into the right place in
+                        <filename>modules/Styles.lua</filename>.</para>
             </glossdef>
         </glossentry>
         <glossentry>
                     extension is specified on a single line.</para>
                 <para>This argument can be specified multiple times. It is fine to specify an
                     extension name more than once, either in the file or on the command line.</para>
+                <para>The file's directory is relative to the path where the command line was
+                    invoked.</para>
+            </glossdef>
+        </glossentry>
+        <glossentry>
+            <glossterm>-stdext</glossterm>
+            <glossdef>
+                <para>Works like <literal>extfile</literal>, except that the directory for the file
+                    is relative to the place where the <filename>LoadGen.lua</filename> file
+                    is.</para>
             </glossdef>
         </glossentry>
     </glosslist>
     <section>
         <title>Styles</title>
+        <para>Styles define how the system </para>
         <para>The different styles have specific meaning for how code is generated by the system.
             These styles are:</para>
         <section>

docs/Load Docs.xpr

             positiveFilePatterns="" showHiddenFiles="false"/>
         <options/>
     </meta>
-    <projectTree name="Load%20Docs.xpr"/>
+    <projectTree name="Load%20Docs.xpr">
+        <file name="Command%20Line%20Options.xml"/>
+        <file name="Style%20Pointer%20C.xml"/>
+        <file name="Styles.xml"/>
+        <file name="ToCreole.xsl"/>
+    </projectTree>
 </project>

docs/Style Pointer C.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>Style Pointer C</title>
+    <para>The <literal>pointer_c</literal> style is the default style. It is also the one that most
+        mimics the way common OpenGL loaders work. This style generates a <filename>.h</filename>
+        and <filename>.c</filename> file. The header file can be included by C and C++; the source
+        file should be compiled as C.</para>
+    <para>Since these are compatible with C, all of the typedefs, enumerations, extension variables,
+        and function pointers are global. The extension variables are of type
+        <literal>int</literal>. Enumerations are <literal>#define</literal>s. The functions are
+        function pointers with mangled names that have been <literal>#define</literal>d into the
+        real OpenGL function name. The latter is done to avoid name conflicts with static linking of
+        certain core OpenGL function names.</para>
+    <para>The loading function that loads the extensions and OpenGL version is called
+            <literal>LoadFunction</literal>, prefixed by a specification-specific prefix. The return
+        value of this function, as well as the value stored in the extension variables, is special.
+        There is an enumeration, prefixed again by the spec-specific prefix.</para>
+    <para>If the value is <literal>LOAD_FAILED</literal>, then the extension was not found in the
+        extension string, so no attempt was made to load it. If the value is
+            <literal>LOAD_SUCCEEDED</literal>, then the extension was loaded in its entirety (all
+        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>
+    <section>
+        <title>Compatibility</title>
+        <para>This style is intended to be maximally compatible with regular OpenGL programs. You
+            should be able to take this header and include it into a standard GL program and use it
+            as is. Furthermore, it should be compatible with other systems like FreeGLUT, GLFW, and
+            so forth, as it provides information in the way that traditional OpenGL headers
+            do.</para>
+        <para>However, in all cases, you should include these generated headers
+                <emphasis>before</emphasis> anything from FreeGLUT, GLFW, etc.</para>
+    </section>
+</article>
+<?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>Styles</title>
+    <para>The <literal>-style</literal> command line option defines how the header and source files
+        are generated. While the styles will have some differences, every style provides a common
+        set of functionality (though exactly how it is exposed differs). Styles provide:</para>
+    <itemizedlist>
+        <listitem>
+            <para>Typedefs for OpenGL concepts (GLenum, etc).</para>
+        </listitem>
+        <listitem>
+            <para>A means to tell whether each of the extensions specified by the user is loaded or
+                not. This is usually exposed via a global variable who's name contains the extension
+                name.</para>
+        </listitem>
+        <listitem>
+            <para>The enumerators for all of the extensions specified as well as any specified
+                OpenGL versions/profiles (where applicable).</para>
+        </listitem>
+        <listitem>
+            <para>Functions (whether function pointers or something else, that's up to the style)
+                for the various extensions specified, as well as any specified OpenGL
+                versions/profiles (where applicable).</para>
+        </listitem>
+        <listitem>
+            <para>A function that will load all function pointers. Even if the style requires static
+                linking, it will still provide a special function to do this. Until this function is
+                called, you cannot use any of the mechanisms to test whether an extension is loaded,
+                nor can you call any other functions.</para>
+            <para>The function's return value will be a status code saying whether it succeeded.
+                Success is defined solely in terms of loading the specified core OpenGL version;
+                therefore, WGL or GLX loader functions will always <quote>succeed</quote>. Test for
+                individual extensions if you want to know what happened there.</para>
+        </listitem>
+        <listitem>
+            <para>Optionally, if using the OpenGL specification, the style will export a number of
+                useful helper functions to query OpenGL version information. This is
+                per-style.</para>
+        </listitem>
+    </itemizedlist>
+    <para>The different types of styles will decide what form these take (enumerators could be
+            <literal>const</literal> variables of some kind instead of the usual
+            <literal>#define</literal>s, for example). But each style must provide this set of
+        information.</para>
+    <section>
+        <title>Core Extensions</title>
+        <para>OpenGL 3.0 introduced the concept of <quote>core extensions.</quote> Normally with
+            extensions, even ARB extensions, the enumerators, functions and typedefs end in the
+            extension type suffix: ARB, EXT, etc. This allows any extension that is to be inducted
+            into the core to have its behavior modified where necessary.</para>
+        <para>With GL 3.0, the ARB changed things by making certain extensions core extensions.
+            These are extensions where their declarations don't have the extension suffix. This
+            represents APIs that do not change between extension and core. As such, the
+            enums/functions/etc are considered part of both the extension and a version of
+            OpenGL.</para>
+        <para>Core extensions are special in that part of OpenGL is effectively in an extension. For
+            example, ARB_uniform_buffer_object is a core extension; all of the functions/enums it
+            defines are part of GL 3.1 as well as the extension.</para>
+        <para>Because of this, it is possible to ask for GL 3.1 (which will provide those
+            functions/enums) <emphasis>and</emphasis> ARB_uniform_buffer_object at the same time. Or
+            to ask for GL 3.0 (which won't provide them) and ARB_uniform_buffer_object. Or to ask
+            for GL 3.1 <emphasis>without</emphasis> explicitly asking for
+            ARB_uniform_buffer_object.</para>
+        <para>The way this works is as follows. If you ask for an extension, no matter what, the
+            system will provide you a way to query whether that extension is loaded. If you don't
+            ask for the extension, but the version number effectively requires that extension
+            (asking for GL 3.1+ requires ARB_uniform_buffer_object), you'll still get the enums and
+            functions, but you <emphasis>won't</emphasis> get a way to query whether that extension
+            specifically is loaded.</para>
+        <para>In short, if you want GL 4.2, but you want to verify whether particular parts are
+                <quote>available,</quote> (if you only get GL 4.1, but there are 4.2 features
+            exposed via extensions), you must explicitly request that extension.</para>
+    </section>
+    <section>
+        <title>Compatibility profile</title>
+        <para>The compatibility profile complicates code generation a bit. The system will do its
+            best to cull inappropriate enumerators/functions based on core/compatibility.</para>
+        <para>However, this may not be possible in every case. For example, take the
+                <literal>GL_QUADS</literal> enumerator. This enumerator was defined way back in GL
+            1.1. But 3.1 removed it, so if you ask for a 3.1 core header, you shouldn't get
+                <literal>GL_QUADS</literal>.</para>
+        <para>The problem is that it didn't <emphasis>stay</emphasis> removed. GL
+            4.0/ARB_tessellation_shader brought it back (though only as a tessellation target).
+            Which means if you ask for a 3.1 core header it should be gone, but if you ask for a 3.1
+            core header that includes ARB_tessellation_shader, it should return. As it should if you
+            ask for a 4.1 core header (with or without ARB_tessellation_shader).</para>
+        <para>This system cannot due that, primarily because the source of the OpenGL specification
+            information (the .spec files, as processed through various scripts) does not provide
+            enough information. The spec files only define what is core or compatibility in the
+            current OpenGL version, not what <emphasis>used</emphasis> to be core for a while, then
+            was only in compatibility, then came back into core.</para>
+        <para>Therefore, the system errs on the side of being inclusive. If it came back into core,
+            it is considered to have never <emphasis>left</emphasis> core OpenGL. Thus, if you ask
+            the system for 3.1, core profiles, you will see <literal>GL_QUADS</literal>, as well as
+            a few others. The number of these are rather few, so it should not be a problem.</para>
+    </section>
+</article>

docs/ToCreole.xsl

+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    xmlns:xs="http://www.w3.org/2001/XMLSchema"
+    xmlns:xd="http://www.oxygenxml.com/ns/doc/xsl"
+    xmlns:db="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    xmlns:fn="http://www.w3.org/2005/xpath-functions"
+    exclude-result-prefixes="xs xd"
+    version="2.0">
+    
+    <xsl:strip-space elements="*"/>
+    <xsl:output method="text" encoding="UTF-8"/>
+    <xsl:output name="text" method="text" encoding="UTF-8"/>
+    
+    <xsl:param name="filePrefix"/>
+    
+    
+    <xsl:template match="/">
+        <xsl:apply-templates select="/db:article/*" mode="root"/>
+    </xsl:template>
+    
+    <!-- Basic structural controls. -->
+    <xsl:template match="db:section" mode="root">
+        <xsl:choose>
+            <xsl:when test="name(preceding-sibling::*[1]) != 'title' and
+                name(preceding-sibling::*[1]) != 'section'">
+                <xsl:apply-templates select="." mode="file"/>
+            </xsl:when>
+            <xsl:when test="ancestor::db:article/processing-instruction(together)">
+                <xsl:apply-templates select="." mode="file"/>
+            </xsl:when>
+            <xsl:otherwise>
+                <xsl:variable name="baseName" select="if(empty(processing-instruction(trope))) then
+                    (string(db:title)) else (substring-before(
+                    substring-after(string(processing-instruction(trope)), 'url=&quot;'), '&quot;'))"/>
+                <xsl:variable name="sectionNum" select="index-of(../db:section, .)"/>
+                <xsl:variable name="prefixedName" select="
+                    if(empty($filePrefix)) then
+                        (concat($sectionNum, ' - ', $baseName))
+                    else
+                        (concat($filePrefix, ' - ', $sectionNum, ' - ', $baseName))"/>
+                <xsl:variable name="filename" select="concat($prefixedName, '.txt')"/>
+                
+                <xsl:result-document format="text" href="{$filename}">
+                    <xsl:apply-templates select="*" mode="file"/>
+                </xsl:result-document>
+            </xsl:otherwise>
+        </xsl:choose>
+    </xsl:template>
+
+    <xsl:template match="db:title" mode="root"/>
+
+    <xsl:template match="db:*" mode="root">
+        <xsl:apply-templates select="." mode="file"/>
+    </xsl:template>
+    
+    
+    <!-- Process the actual text data. -->
+    <xsl:template match="db:para" mode="file">
+        <xsl:if test="ancestor::db:blockquote or ancestor::db:epigraph">
+            <xsl:text>-></xsl:text>
+        </xsl:if>
+        <xsl:apply-templates select="*|text()" mode="#current"/>
+        <xsl:choose>
+            <xsl:when test="ancestor::db:blockquote">
+                <xsl:text>
+</xsl:text>
+            </xsl:when>
+            <xsl:when test="following-sibling::*">
+                <xsl:text>
+
+</xsl:text>
+            </xsl:when>
+            <xsl:otherwise>
+                <xsl:text>
+</xsl:text>
+            </xsl:otherwise>
+        </xsl:choose>
+    </xsl:template>
+    
+    <xsl:template match="db:formalpara" mode="file">
+        <xsl:text>**</xsl:text>
+        <xsl:value-of select="db:title"/>
+        <xsl:text>**: </xsl:text>
+        <xsl:apply-templates select="db:para" mode="#current"/>
+        <xsl:text>
+</xsl:text>
+    </xsl:template>
+    
+    <!--
+    <xsl:template match="db:footnote" mode="file">
+        <xsl:text>[[hottip:</xsl:text>
+        <xsl:value-of select="if(@label) then @label else '*'"/>
+        <xsl:text>:</xsl:text>
+        
+        <xsl:apply-templates select="db:para/(*|text())" mode="#current"/>
+        <xsl:text>]]</xsl:text>
+    </xsl:template>
+    -->
+    
+    <xsl:template match="db:emphasis" mode="file">
+        <xsl:text>//</xsl:text>
+        <xsl:apply-templates select="*|text()" mode="#current"/>
+        <xsl:text>//</xsl:text>
+    </xsl:template>
+    
+    <xsl:template match="db:emphasis[@role = 'strong'">
+        <xsl:text>**</xsl:text>
+        <xsl:apply-templates select="*|text()" mode="#current"/>
+        <xsl:text>**</xsl:text>
+    </xsl:template>
+    
+    <xsl:template match="db:foreignphrase" mode="file">
+        <xsl:text>//</xsl:text>
+        <xsl:apply-templates select="*|text()" mode="#current"/>
+        <xsl:text>//</xsl:text>
+    </xsl:template>
+    
+    <xsl:template match="db:personname" mode="file">
+        <xsl:text>**</xsl:text>
+        <xsl:apply-templates select="*|text()" mode="#current"/>
+        <xsl:text>**</xsl:text>
+    </xsl:template>
+    
+    <xsl:template match="db:firstname" mode="file">
+        <xsl:if test="preceding-sibling::db:surname">
+            <xsl:text> </xsl:text>
+        </xsl:if>
+        <xsl:apply-templates select="*|text()" mode="#current"/>
+    </xsl:template>
+    
+    <xsl:template match="db:surname" mode="file">
+        <xsl:if test="preceding-sibling::db:firstname">
+            <xsl:text> </xsl:text>
+        </xsl:if>
+        <xsl:apply-templates select="*|text()" mode="#current"/>
+    </xsl:template>
+    
+    <xsl:template match="db:quote" mode="file">
+        <xsl:text>&quot;</xsl:text>
+        <xsl:apply-templates select="*|text()" mode="#current"/>
+        <xsl:text>&quot;</xsl:text>
+    </xsl:template>
+    
+    <xsl:template match="db:link" mode="file">
+        <xsl:text>[[</xsl:text>
+        <xsl:value-of select="@xlink:href"/>
+        <xsl:text>|</xsl:text>
+        <xsl:apply-templates select="*|text()" mode="#current"/>
+        <xsl:text>]]</xsl:text>
+    </xsl:template>
+
+<!--
+    <xsl:template match="db:olink[@targetptr]" mode="file">
+        <xsl:text>[[</xsl:text>
+        <xsl:text>{{</xsl:text>
+        <xsl:value-of select="@targetptr"/>
+        <xsl:text>}}</xsl:text>
+        <xsl:text> </xsl:text>
+        <xsl:apply-templates select="*|text()" mode="#current"/>
+        <xsl:text>]]</xsl:text>
+    </xsl:template>
+    
+    <xsl:template match="db:olink[@targetdir]" mode="file">
+        <xsl:text>[[</xsl:text>
+        <xsl:text>{{</xsl:text>
+        <xsl:value-of select="@targetdir"/>
+        <xsl:text>}}</xsl:text>
+        <xsl:text> </xsl:text>
+        <xsl:apply-templates select="*|text()" mode="#current"/>
+        <xsl:text>]]</xsl:text>
+    </xsl:template>
+    
+    <xsl:template match="db:olink" mode="file">
+        <xsl:text>{{</xsl:text>
+        <xsl:value-of select="."/>
+        <xsl:text>}}</xsl:text>
+    </xsl:template>
+-->
+    
+    <xsl:template match="db:phrase[@role='title']" mode="file">
+        <xsl:text>//**</xsl:text>
+        <xsl:apply-templates select="*|text()" mode="#current"/>
+        <xsl:text>**//</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:template>
+    
+    <xsl:template match="db:section" mode="file">
+        <xsl:text>==</xsl:text>
+        <xsl:value-of select="db:title[1]"/>
+        <xsl:text>==</xsl:text>
+        <xsl:text>
+
+</xsl:text>
+        <xsl:apply-templates select="*|text()" mode="#current"/>
+    </xsl:template>
+    
+    <xsl:template match="db:blockquote" mode="file">
+        <xsl:apply-templates select="*|text()" mode="#current"/>
+        <xsl:text>
+</xsl:text>
+    </xsl:template>
+    
+    <xsl:template match="text()" mode="file">
+        <xsl:variable name="norm" select="normalize-space()"/>
+        <xsl:if test="substring($norm, 1, 1) != substring(., 1, 1) and (string-length($norm) > 0)">
+            <xsl:text> </xsl:text>
+        </xsl:if>
+        <xsl:value-of select="$norm"/>
+        <xsl:if test="substring($norm, string-length($norm), 1) != substring(., string-length(.), 1) and (string-length($norm) > 0)">
+            <xsl:text> </xsl:text>
+        </xsl:if>
+    </xsl:template>
+    
+    <xsl:template match="db:title" mode="file"/>
+</xsl:transform>