XML Format Consultation: Merging <groups> and <enums>

[Perksey]

Introduction

One thing that's annoyed me about the current XML schema is that the strongly-typed enum groupings are separate to the rest of the specification. Granted, they aren't that useful in C but downstream consumers (such as my Silk.NET library for C#) who are using the XML specification to bind OpenGL to languages that do better support strongly typed enums.

Today's problem

The problem with the group tags being separate is that there's a lesser emphasis on the correctness of the groupings. And, to be fair to the Khronos Group, I see why they wouldn't need to worry about the groupings as they don't use them themselves and, as such, won't want to dedicate cycles to ensuring the groupings' correctness.

I want to tackle this problem by merging the <enum> blocks and the <group> blocks. If these structures are merged, it encourages spec editors to group the enums properly upon creating a new extension, and should hopefully solve the problem of invalid groupings going forward because if creating proper enum groups is a requirement upon vendors and extension writers, we won't have any group problems going forward.

Solution in action

My proposed solution uses already established schema elements such that it wouldn't be too breaking for the Khronos Group themselves, but may affect downstream consumers. This is why I want to consult with these consumers so that we can establish whether this is a worthy enhancement to the spec.

Current syntax

<groups>
    <group name="GroupName">
        <enum name="GL_ENUM_NAME" />
    </group>
    <group name="AnotherGroupAMD">
        <enum name="GL_ANOTHER_ENUM_AMD" />
    </group>
    <group name="AGroupThatReusesTokensEXT">
        <enum name="GL_ENUM_NAME" />
        <enum name="GL_ANOTHER_ENUM_AMD" />
    </group>
</groups>

Proposed Syntax

<enums namespace="GL" start="0x0001" end="0x0002">
    <enum value="0x0001" name="GL_ENUM_NAME" group="GroupName,AGroupThatReusesTokensEXT" />
    <enum value="0x0002" name="GL_ANOTHER_ENUM_AMD" group="AnotherGroupAMD,AGroupThatReusesTokensEXT" />
</enums>

Pros

• This syntax doesn't require multiple enum definitions for reuse of an enum in multiple groups. (we will use a comma to separate groups in the group element i.e. group="FirstGroup,SecondGroupINTEL")
• Each enum addition to the spec being in its own group encourages extension authors to place all new enums in their own group, eliminating the need for contributors such as myself to go back into the spec later on to add the groups for them.
• No impact to the Khronos group.

Cons

• May affect downstream consumers that rely on the group tags (we could probably think of some way to tackle this, but that's why this is a consultation and not a PR)

Proposed course of action

1. Add the group attributes to the correct enums with the data as outlined by this proposal. The <group> blocks will remain unchanged for now.
2. Announce a date (either here or somewhere else where we can capture the attention of spec consumers) that the Khronos Group intends to remove the <group> blocks.
3. Remove the <group> blocks after as many enums have been grouped as possible.

Closing

I understand that the groupings affect the Khronos group in no way shape or form, but this change matters plenty to downstream consumers that might be depending on the groups and this change will be doing them a favour in the long-term.

Thank you for reading and I hope you take this into consideration.

Version History

Date	Message
06/12/2019	Initial proposal.
12/12/2019	Switch gears to using group attributes instead, eliminating problems with duplicates as suggested by Jon and jvbsl.
17/12/2019	Add token reuse using the \| separator
31/12/2019	Switch to the , separator for token reuse

Stakeholders

OpenGLAda - @flyx cl-opengl - @3b CSGL - @thatonecheetah opengl4csharp - @giawa OpenGLDotNet - @carmack78 OpenGL.Net - @luca-piccioni OpenTK - @varon @jvbsl @frederikja163 Silk.NET - myself @frederikja163 @AzyIsCool dglOpenGL - @saschawillems JOGL - @sgothel LWJGL - @spasi LuaGL - @drahosp glMLite - @fccm ModernGL - @cprogrammer1994 PyOpenGLng - @FabriceSalvaire Racket OpenGL - @stephanh42 Ruby OpenGL - @vaiorabbit

Please tag anyone I may have missed who might be impacted by this.

[3b]

cl-opengl is OK with switching to group attributes, We are using a fork temporarily, and will switch to new format before next update (if I have any changes that need pushed upstream, I'd probably rather make them to the new format anyway).

[Perksey]

Ok cool, in which case the assignee of this issue should probably change to whoever is going to decide on the date of the old block removal (as currently it's still assigned to me)

[3b]

cl-opengl is switched to new format, though still not released with either version of the new groups, since it is missing some group+enum combinations that affects existing code. working on that in #431.

[Perksey]

Awesome!