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.

[oddhack]

The expression of enum group allocation and use that the current XML contains is important to us - the SGI enum registry was literally the place gl.xml began from. I don't see how you can simultaneously use the enums tags for semantic grouping and numerical grouping without simply replicating every enum in at least two places, so I'm not feeling much enthusiasm for this idea - although I applaud your efforts to construct it in terms of the existing schema.

[Perksey]

Yeah I understand that, and perhaps we need to look further into the current state of the groupings to look at what can be done to achieve the main goal: enforcing validity of groupings without causing any further trouble for vendors and spec editors.

[oddhack]

A way of doing this that would probably have no effect on current consumers is to move the group attribute into the individual <enum> tags rather than using <enums> as a grouping mechanism. It is kinda wordy (expands the file size by 5-10% at a guess), but since it's just a new attribute on an existing tag, it should be ignored by our scripts, and probably by most processing tools unaware of it.

[Perksey]

Yeah that works for me, I’ll update the proposal next time I’m on a computer.

…

On Thu, 12 Dec 2019 at 10:37, Jon Leech ***@***.***> wrote: A way of doing this that would probably have no effect on current consumers is to move the group attribute into the individual <enum> tags rather than using <enums> as a grouping mechanism. It is kinda wordy (expands the file size by 5-10% at a guess), but since it's just a new attribute on an existing tag, it should be ignored by our scripts, and probably by most processing tools unaware of it. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#335?email_source=notifications&email_token=ACVEYI65PGT3FAECFPX345TQYIH5TA5CNFSM4JW74LVKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEGWHKMY#issuecomment-564950323>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACVEYI7OEJX463XQCQXHDJ3QYIH5TANCNFSM4JW74LVA> .

[oddhack]

OK. If we go this way, please add the attributes at the end of the tag, not the beginning - keeping the name & value first is preferable for me.

[Perksey]

Yeah I agree with that 100%, putting it elsewhere would make it a lot harder to edit the enums.

…

On Thu, 12 Dec 2019 at 11:41, Jon Leech ***@***.***> wrote: OK. If we go this way, please add the attributes at the end of the tag, not the beginning - keeping the name & value first is preferable for me. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#335?email_source=notifications&email_token=ACVEYIZBZQZ6FOWZV3ARXL3QYIPPDA5CNFSM4JW74LVKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEGWMXQY#issuecomment-564972483>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACVEYI6NSXKSM75BUHGTM4LQYIPPDANCNFSM4JW74LVA> .

[Perksey]

I've updated the issue, let me know if there's any further comments. I've also been hearing radio silence from the downstream consumers which is slightly worrying.

[fccm]

Maybe you also want to CC dbuenzli/tgls

[Perksey]

@dbuenzli any comments?

[null77]

Impacts ANGLE as we use gl.xml to generate our entry points and other files. @null77 is my handle.

[Perksey]

@null77 Do you use the blocks at all? This proposal only affects this portion of the spec, if you're not parsing anything else then you won't be affected by this issue.

[null77]

We do. They're helpful when converting a GLenum to string as some GLenum values overlap.

[Perksey]

Ah ok. In the Proposed course of action section of this document I outline a... well... proposed course of action. Is this good enough to ensure a smooth transition over to the group attributes?

[null77]

The motivation sounds reasonable. Implementing a presubmit check that validates new enums have a group tag also sounds like it would solve your problem without causing conflicts downstream. What do you think? I'm assuming your motivation is that the groups aren't reliable right now.

[Perksey]

Yeah I was thinking about adding in a check as we already developed a small error checker application internally, but a presubmit check won’t fix the problem where the groupings are separate and, as a result, spec editors have to go out of their way to ensure group correctness whereas if they’re declared inline with the enum, it’s a lot easier for spec editors to declare the groups. I want to work with downstream consumers before we do anything destructive like get rid of the blocks - I only want to do this once I know everyone’s ready

…

On Mon, 16 Dec 2019 at 22:54, Jamie Madill ***@***.***> wrote: The motivation sounds reasonable. Implementing a presubmit check that validates new enums have a group tag also sounds like it would solve your problem without causing conflicts downstream. What do you think? I'm assuming your motivation is that the groups aren't reliable right now. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#335?email_source=notifications&email_token=ACVEYI2GOVFPXPUMWSTVBWTQZABJDA5CNFSM4JW74LVKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEHANACQ#issuecomment-566284298>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACVEYIYDYBMFWNBCIDFHGG3QZABJDANCNFSM4JW74LVA> .