Commits

Jason McKesson committed 019a4e1

Updated docs.

Comments (0)

Files changed (3)

Structure_Reference.wiki

+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.
+
+<<toc>>
+
+==Concepts==
+
+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 "parsed;" 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 "copied" by simply using another variable.
+
+A structure is built as a nested series of tables. So you would define one like this:
+
+{{{
+local my_struct =
+{
+  { type="foo", },
+  { type="bar", },
+}
+}}}
+
+The contents of the base structure is an array of values. Once you have created the table, the actual datastructure is created as follows:
+
+{{{
+local Structure = require "Structure"
+
+Structure.BuildStructure(my_struct)
+}}}
+
+The return value is a special object that should be returned along with your style.
+
+Each element of a structure is called an **action.** The type of action is defined by the {{{type}}} field. Using an invalid type will result in a build-time error (ie: {{{BuildStructure}}} 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.
+
+Each type can have a number of attributes. Some attributes are specific to certain types, while others can be used anywhere.
+
+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.
+
+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 {{{BuildStructure}}} will halt with a stack overflow (or execute infinitely).
+
+===Context===
+
+There is a notion of a current **context**. 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.
+
+If an action provides some new context variable(s), then all child actions may access that.
+
+Some actions //require// 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.
+
+Similarly, actions cannot modify already existing context variables. So you cannot nest actions that provide the same context variable(s).
+
+In the reference table below, there will be text that says, "must be within the scope of." This means that the action needs to be inside something that provides this context variable.
+===Current Style===
+
+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.
+
+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 {{{WriteExtVariable}}}. When generating your header file, you want it to write an {{{extern}}} declaration, but in your source file, it should write it as a non-{{{extern}}} definition. What you can do is define a pair of sub-tables of your main style table. A table called {{{header}}} would have one version of {{{WriteExtVariable}}}, while the table called {{{source}}} would have another version.
+
+Thus, you could use the same structural element to process both. Like this:
+
+{{{
+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,
+  }
+}
+}}}
+
+When the system goes to find {{{WriteExtVariable}}}, 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, //then// it errors out. Thus, every additional substyle //increases// the number of functions available; it never reduces them.
+
+Indeed, the {{{style}}} parameter itself uses similar resolution methods. For example, you could have a second table inside the {{{header}}} table also given the name {{{source}}} (so it's full name relative to the main style is {{{header.source}}}). If you are inside the {{{header}}} style and then ask for the {{{source}}} style, you will get the {{{header.source}}} sub-style.
+
+This is a very useful tool for making large structure construction more manageable.
+==Action Reference==
+
+This is a list of all of the actions and their associated attributes.
+
+When an action says, "Provides access to the X parameter," this also means that the action //cannot nest// with any action that provides this parameter. Including itself.
+
+**file**:
+
+Creates a tabbed-file. See the TabbedFile.lua module to understand what this is. The default function parameters are: {{{(basename, options)}}}
+
+* {{{name}}}: The exact name of a function to call that returns the full pathname of the file to create
+
+Provides access to the {{{hFile}}} parameter.
+
+Note that you really need the {{{basename}}} 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 {{{util.ParsePath}}} for this. Thus, your code should look like:
+
+{{{
+function style_name.GetFilenameFunc(basename, ...)
+  local base, dir = util.ParsePath(basename)
+  local filename = --compute filename here.
+  return dir .. filename
+end
+}}}
+
+**block**:
+
+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: {{{(hFile, spec, options)}}}
+
+* {{{name}}}: 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 "{{{WriteBlockBegin}}}"; similarly the ending function is prefixed with "{{{WriteBlockEnd}}}"
+
+Must be within the scope of {{{hFile}}}.
+
+**group**:
+
+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.
+
+**write**:
+
+Calls a function to write something to the file. The default parameters to the function are {{{(hFile, specData, spec, options)}}}.
+
+* {{{name}}}: The base name of the function that does the actual writing. The full name will be prefixed by "{{{Write}}}".
+
+Must be within the scope of {{{hFile}}}.
+
+**blank**:
+
+Writes a blank line to the file.
+
+Must be within the scope of {{{hFile}}}.
+
+**filter**:
+
+Will execute its child actions only if the given function returns true. The default parameters are {{{(hFile, specData, spec, options)}}}.
+
+* {{{name}}}: The base name of the function that does filtering. The full name will be prefixed by "{{{Filter}}}".
+* {{{neg}}}: If this is true, then the meaning of the return value is inverted. That is, if the function returns true, then it will //not// process the children. This is useful for reusing filter functions in opposite ways without having to write a new one.
+
+**ext-iter**:
+
+Executes its children once for every extension that the user explicitly asked to generate code for.
+
+Provides access to the {{{extName}}} parameter.
+
+**version-iter**:
+
+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.
+
+Provides access to the {{{version}}} parameter.
+
+**sub-version-iter**:
+
+Execute its children once for every version less than or equal to the current {{{version}}} parameter.
+
+Must be within the scope of {{{version}}}. Provides access to the {{{sub_version}}} parameter.
+
+This is useful for generating a group of functions or files that do something for each version, and for each version of OpenGL <= 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 //up to// that version of OpenGL and not just within it.
+
+**core-ext-iter**:
+
+Executes its children once for every core extension of the current {{{version}}} parameter. Note that this will iterate over the core extensions introduced in version //only.//
+
+Must be within the scope of {{{version}}}. Provides access to the {{{extName}}} parameter.
+
+**core-ext-cull-iter**:
+
+Executes its children once for every core extension of the current {{{version}}} parameter which //was not requested// 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.
+
+Must be within the scope of {{{version}}}. Provides access to the {{{extName}}} parameter.
+
+**enum-iter**:
+
+Executes its children once for every enumerator within scope. "Scope" is defined by the {{{extName}}} and/or {{{version}}} parameters. If {{{extName}}} is available, then it will iterate over all enums in the extension. If {{{version}}} is available, then it will iterate over all enums that were introduced within that particular version (and //only// them). If both are available, {{{extName}}} takes priority.
+
+Must be within the scope of {{{extName}}} or {{{version}}}. Provides access to the {{{enum}}} and {{{enumTable}}} parameters.
+
+**func-iter**:
+
+Executes its children once for every function within scope. Scope is defined as for {{{enum-iter}}}.
+
+Must be within the scope of {{{extName}}} or {{{version}}}. Provides access to the {{{func}}} and {{{typemap}}} parameters.
+
+**enum-seen**:
+
+This is a special action which records which enumerators were iterated over within its scope. Every time an {{{enum-iter}}} finishes processing an enumerator, the enumerator name that was processed will be recorded in {{{enumSeen}}}. 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.
+
+To see if an enumerator was processed already, use {{{enumSeen[enum.name]}}}. The value stored there will be a string containing the extension name or the version that it was most recently seen within.
+
+Provides access to the {{{enumSeen}}} parameter.
+
+Note that if you place a filter within an {{{enum-iter}}} block that is in an {{{enum-seen}}} scope, the filter's active/inactive status //will not affect// whether {{{enumSeen}}} will be updated. It doesn't matter if nothing was written; the enumerator being iterated over is enough.
+
+**func-seen**:
+
+Works like {{{enum-seen}}}, except for functions.
+
+Provides access to the {{{funcSeen}}} parameter.
+
+===Common Attributes===
+
+Here is a list of attributes that can be used in any action (or at least a lot of them).
+
+**name**:
+
+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.
+
+**style**:
+
+Adds a new sub-style scoping. It fetches the style table using the rules specified above in the Current Style section.
+
+**optional**:
+
+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, //UNLESS// 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 {{{neg}}} is set, in which case it will flip that into {{{true}}}, thus always processing children if the function isn't present).
+
+**first**:
+
+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 //most recent// iteration loop.
+
+The interaction with filters can play havoc with this. {{{first}}} 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 //never// be executed.
+
+**last**:
+
+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.
+
+**cond**:
+
+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.
+
+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 //only// be used in the same context that their corresponding iterators can:
+
+* {{{ext-iter}}}
+* {{{version-iter}}}
+* {{{core-ext-iter}}}
+* {{{core-ext-cull-iter}}}
+* {{{enum-iter}}}
+* {{{func-iter}}}
+* {{{core-funcs}}}: Returns true if the spec has core functions/enumerators at all. Basically, checks if the specification is OpenGL and not WGL or GLX. Technically {{{version-iter}}} would do the same job, but in a less obvious way.
+
+==Function Parameters==
+
+Here are a list of the various function parameters, with references to the actions that provide them.
+
+Again, //DO NOT MODIFY THEM!//
+
+**specData**:
+
+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.
+
+You can see what specData looks like by reading {{{glspecs/glspec.lua}}}. {{{specData}}} is derived from this table, but with some modifications. The modifications are detailed in the comments at the top of {{{modules/LoadLuaSpec.lua}}}. They're primarily convenience stuff, to make it easier to find enums and functions by name and so forth.
+
+Normally, you should not need to look at this data structure directly. So include it in a parameter list sparingly.
+
+This parameter is always available.
+
+**spec**:
+
+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:
+
+{{{
+spec.EnumNamePrefix() .. enumName
+}}}
+
+There are a number of spec functions that return prefix strings or other spec-based strings. You can find these in the {{{modules/Specs.lua}}} file, with a comment stating what each one returns.
+
+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 {{{data}}} directory, using the file format {{{data/<specName>_spec<data>.lua}}}.
+
+This parameter is always available.
+
+**options**:
+
+The options data structure. It contains the options processed from the command-line. Among these is {{{extensions}}}, the list of extension names that are being explicitly written. You can tell which spec is being used with {{{options.spec}}}, but it's better to rely on the {{{spec}}} parameter as seen below.
+
+This parameter is always available.
+
+**basename**:
+
+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 {{{file}}} action types.
+
+This parameter is always available.
+
+**hFile**:
+
+A {{{TabbedFile}}}. This is a special kind of Lua IO file. It supports all of the Lua IO methods (//DO NOT CLOSE IT!//), 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.
+
+This parameter is provided by the {{{file}}} action.
+
+Note that you must use it with Lua's member calling conventions ({{{hFile:write}}}, for example). If you try to use {{{io.write}}}, things will break.
+
+{{{hFile:inc}}} and {{{hFile:dec}}} are functions that increment/decrement the current indention level. The indention can be preserved with {{{hFile:push}}} and restored with {{{hFile:pop}}}.
+
+The {{{TabbedFile}}} also offers the ability to do string formatting directly into the write. {{{hFile:fmt}}} takes a format string and some parameters, forwards the parameters to {{{string.format}}}, then writes that string as a line.
+
+There are block writing functions, {{{hFile:writeblock}}} and {{{hFile:fmtblock}}}. These functions will split the written string into individual lines and indent each one.
+
+If you don't want indented writes, then use {{{hFile:rawwrite}}} and {{{hFile:rawfmt}}}.
+
+**extName**:
+
+The base name of an extension. Usually paired with {{{specData}}}, as the name alone isn't terribly useful. You can get the list of enumerators and functions defined by this extension with {{{specData[extName].enums/funcs}}}. These are not named of enumerators and functions; they're the actual part of the {{{specData}}} that defines everything about that enum/func.
+
+This parameter is provided by the {{{ext-iter}}}, {{{core-ext-iter}}}, and {{{core-ext-cull-iter}}} actions.
+
+**version**:
+
+A //string// (remember this) that contains the version of interest. Since it's a string, you need to apply {{{tonumber}}} to it to get a proper number.
+
+This parameter is provided by the {{{version-iter}}} action.
+
+**sub_version**:
+
+A //string// (remember this) that contains a version between the first version and the current {{{version}}} version.
+
+This parameter is provided by the {{{sub-version-iter}}} action.
+
+**enum**:
+
+This is an enumeration. Not the //name// of an enumeration; the enumeration itself. It contains the name {{{enum.name}}}, but it also contains versioning information and so forth. It is an entry from the {{{specData.enumerations}}} table.
+
+This parameter is provided by the {{{enum-iter}}} action.
+
+If you want to get the value of an enumerator, you cannot simply use {{{enum.value}}}. You need the {{{enum}}} and the {{{enumTable}}} (see below). Then, you use {{{common.ResolveEnumValue}}}, where {{{common}}} is the {{{CommonStyle}}} module table.
+
+**enumTable**:
+
+A table of {{{enum}}}s, indexed by enumeration name. It comes from {{{specData.enumtable}}}.
+
+This parameter is provided by the {{{enum-iter}}} action.
+
+**func**:
+
+This is a function. As with {{{enum}}}, it is not merely the name of a function (that's {{{func.name}}}); it is the function itself. It is an element taken from the {{{specData.funcData.functions}}} array. It contains many properties of a function.
+
+This parameter is provided by the {{{func-iter}}} action.
+
+If you want to get the parameters (C-style) in a function, you can use {{{common.GetFuncParamList}}}, which requires a {{{typename}}} (see below). Otherwise, you would have to deal with the many difficulties of pulling a viable parameter list from a {{{func}}}.
+
+**typemap**:
+
+This is a mapping between types as defined in {{{func}}} (for parameters and values) and types as defined by C/C++, as well as the standard OpenGL/system typedefs and such. It is from {{{specData.typemap}}}.
+
+This parameter is provided by the {{{func-iter}}} action.
+
+**enumSeen**:
+
+A table indexed by enumerator name. If an entry is present, then the enumerator was already seen at least once before.
+
+This parameter is provided by the {{{func-seen}}} action.
+
+**funcSeen**:
+
+A table indexed by function name. If an entry is present, then the function was already seen at least once before.
+
+This parameter is provided by the {{{func-seen}}} action.
+

Style_Creation.wiki

-The style system is designed to be extensible and as simple as possible. That doesn't mean it's not somewhat complex.
+The style system is designed to be extensible. But it is also somewhat complex. There are two concepts that are important: a style and a structure.
 
-A {{{style}}} 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.
+A {{{structure}}} is a Lua table that effectively defines the basic layout of where information goes in the generated files. It also defines which files are generated. In a structure, you can do things like loop over all the extensions and/or versions. The structure system is very flexible, allowing you to create virtually any kind of output you could imagine.
 
-You should not need to keep state between function invocations (the {{{pointer_c}}} style works completely statelessly, relying only on function arguments). However, if you need state, you can create it by using the {{{Create}}} function to associate actual state with each instance. The system guarantees that the particular table returned by your style's {{{Create}}} function will only be used to generate a single header/source pair.
+The structure defines the basic layout of everything, but it doesn't define the actual words and characters that get written. This is defined by the {{{style}}}. Styles and structures interact; structures can say things like, "Loop over all extensions and call this style function for each." The particular style function will decide what to do with the extension it is given. Because of this, different styles can //share// the same structure. {{{pointer_c}}} and {{{pointer_cpp}}} both use the style defined in {{{StyleCommon}}}, even though they do very different things.
 
-The {{{style}}} table will need two sub-tables named {{{source}}} and {{{header}}}. They contain functions for generating material for source and header files, respectively. Most of the functions are in these two sub-tables.
+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:
+
+{{{
+{ type="ext-iter",
+  { type="block", name="ExtensionFunctionDef(hFile, extName, spec, options),
+    { type="func-iter",
+      { type="write", name="LoadFunctionPtr(hFile, func, typemap, spec, options)", },
+    },
+  },
+},
+}}}
+
+The first section has an {{{ext-iter}}}, 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 {{{block}}} that defines the beginning and end of the function. Inside of the block is a {{{func-iter}}}, 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 {{{write}}} statement that writes something for each function.
+
+The stuff in the {{{name}}} tags represent (part of) the name of functions stored within the //style//. Exactly how this is interpreted depends on the particular statement. For example, the {{{write}}} statement above will call a function named {{{//Write//LoadFunctionPtr}}}, because the write statement always appends {{{Write}}} to its statements.
+
+The {{{block}}} statement is a bit more complex, as it will call two separate functions: {{{WriteBlockBeginExtensionFunctionDef}}} and {{{WriteBlockEndExtensionFunctionDef}}}. 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.
+
+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.
+
+The parameter list is actually quite special. Each parameter name has a very specific meaning and stores very specific data (which you must //never modify//). But different parameters are available at different times. For example, {{{extName}}} represents the name of the current extension. But there can only be a "current extension" when you are iterating over a group of extensions. Likewise, {{{func}}} is a function loaded from the appropriate spec file, but it is only available while iterating over a set of functions.
+
+As with function names, if a parameter is specified in a place where it is not made available (such as providing {{{func}}} to {{{ExtensionFunctionDef}}}), a runtime error explaining the problem will occur.
+
+This is a simple overview of the process. There is a rather lot more complexity than that.
+
+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.
 
 <<toc>>
 
-==Naming convention==
+==Making the Structure==
 
-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:
+This page will provide a basic overview for making a simple structure. [[Structure_Reference|The reference page]] has more in-depth documentation about all aspects of structure creation.
 
-**options**:
 
-The options data structure. It contains the options processed from the command-line. Among these is {{{extensions}}}, the list of extension names that are being explicitly written. You can tell which spec is being used with {{{options.spec}}}, but it's better to rely on the {{{spec}}} parameter as seen below.
 
-**hFile**:
-
-A {{{TabbedFile}}}. This is a special kind of Lua IO file. It supports all of the Lua IO methods (//DO NOT CLOSE IT!//), 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.
-
-Note that you must use it with Lua's member calling conventions ({{{hFile:write}}}, for example). If you try to use {{{io.write}}}, things will break.
-
-{{{hFile:inc}}} and {{{hFile:dec}}} are functions that increment/decrement the current indention level. The indention can be preserved with {{{hFile:push}}} and restored with {{{hFile:pop}}}.
-
-The {{{TabbedFile}}} also offers the ability to do string formatting directly into the write. {{{hFile:fmt}}} takes a format string and some parameters, forwards the parameters to {{{string.format}}}, then writes that string as a line.
-
-There are block writing functions, {{{hFile:writeblock}}} and {{{hFile:fmtblock}}}. These functions will split the written string into individual lines and indent each one.
-
-If you don't want indented writes, then use {{{hFile:rawwrite}}} and {{{hFile:rawfmt}}}.
-
-**specData**:
-
-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.
-
-You can see what specData looks like by reading {{{glspecs/glspec.lua}}}. {{{specData}}} is derived from this table, but with some modifications. The modifications are detailed in the comments at the top of {{{modules/LoadLuaSpec.lua}}}. They're primarily convenience stuff, to make it easier to find an enum by its enumeration name and so forth.
-
-**spec**:
-
-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:
-
-{{{
-spec.EnumNamePrefix() .. enumName
-}}}
-
-There are a number of spec functions that return prefix strings or other spec-based strings. You can find these in the {{{modules/Specs.lua}}} file, with a comment stating what each one returns.
-
-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 {{{data}}} directory, using the file format {{{data/<specName>_spec<data>.lua}}}. 
-
-**extName**:
-
-The base name of an extension. Usually paired with {{{specData}}}, as the name alone isn't terribly useful. You can get the list of enumerators and functions defined by this extension with {{{specData[extName].enums/funcs}}}. These are not named of enumerators and functions; they're the actual part of the {{{specData}}} that defines everything about that enum/func.
-
-**enum**:
-
-This is an enumeration. Not the //name// of an enumeration; the enumeration itself. It contains the name {{{enum.name}}}, but it also contains versioning information and so forth. It is an entry from the {{{specData.enumerations}}} table.
-
-If you want to get the value of an enumerator, you cannot simply use {{{enum.value}}}. You need the {{{enum}}} and the {{{enumTable}}} (see below). Then, you use {{{common.ResolveEnumValue}}}, where {{{common}}} is the {{{CommonStyle}}} module table.
-
-**enumTable**:
-
-A table of {{{enum}}}s, indexed by enumeration name. It comes from {{{specData.enumtable}}}.
-
-**func**:
-
-This is a function. As with {{{enum}}}, it is not merely the name of a function (that's {{{func.name}}}); it is the function itself. It is an element taken from the {{{specData.funcData.functions}}} array. It contains many properties of a function.
-
-If you want to get the parameters (C-style) in a function, you can use {{{common.GetFuncParamList}}}, which requires a {{{typename}}} (see below). Otherwise, you would have to deal with the many difficulties of pulling a viable parameter list from a {{{func}}}.
-
-**typemap**:
-
-This is a mapping between types as defined in {{{func}}} (for parameters and values) and types as defined by C/C++, as well as the standard OpenGL/system typedefs and such. It is from {{{specData.typemap}}}.
-
-**version**:
-
-A //string// (remember this) that contains the version of interest. Since it's a string, you need to apply {{{tonumber}}} to it to get a proper number.
 
 ==Library functions==
 
 * The user should be able to supply a prefix with the {{{-prefix}}} option. The user should be able to generate two separate source/header files with the //exact same options// 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\\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.\\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).\\The prefix string is in {{{options.prefix}}}. Note that it will always be present; if you want to test for a user-defined prefix, test it against the empty string.
 
 So prefix names that can conflict with the user-prefix //and// the spec's prefix.
-==File structure==
-
-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.
-
-{{{
-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)
-}}}
-
-And here is the equivalent structure for the source files:
-
-{{{
-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)
-}}}
-
 ==Style function reference==
 
 The file {{{modules/SampleStyle.lua}}} contains a file that you can simply copy and paste to start making a style. Every function you need to define is listed, as well as comments explaining exactly what they should do. Coupled with this documentation, you should be well on your way to getting a style working.

Style_Pointer_CPP.wiki

 The enumerators are actual C++ enums now. There is no enumeration name; all of the enums live in one big enumeration. Because the enumerators are namespace-qualified now, there is no need to put the {{{(W)GL(X)_}}} in front of them. So we do not. However, this causes two problems:
 
 # Some enumerators ({{{2D}}}, for example. Yes, that is an OpenGL enumerator; it's for feedback rendering) begin with characters that C++ doesn't allow as identifiers. Thus, these enumerators are prefixed with an "{{{_}}}" character. So {{{2D}}} becomes {{{_2D}}}.
-# Certain enumerators use widely used by OS's for various things. Windows for example {{{#define}}}s {{{TRUE}}} and {{{FALSE}}}, 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 "{{{_}}}" character. So {{{TRUE}}} becomes {{{TRUE_}}}.
+# Certain enumerators use widely used by OS's for various things. Windows for example {{{#define}}}s {{{TRUE}}} and {{{FALSE}}}, among others. There's no automated way to detect this, 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 {{{TRUE}}} becomes {{{TRUE_}}}.
 
 The functions are function pointers, but their names are not hidden behind a {{{#define}}}. This should allow code-completion tools to be more useful. They also aren't prefixed with {{{(w)gl(X)}}}, since they live in a namespace.