You keep excusing poor wording and incomprehensibility by the need for being exact. By your own words, something which is understandably written cannot possibly be a specification because “a specification has to be exact”.
You know what I think this is? Elitism.
A specification can as well be criticized with regard to its clarity as any other documentation.
An ad hominem and a strawman. That’s a double-fallacy score
I never said that a specification can’t be criticized for clarity. I said that your criticisms are generally invalid. I’m arguing against your argument, not that everything is A-OK in the spec.
Your criticisms are not all criticisms. Your criticism is that the specification is systemically unclear and poorly specified. I don’t agree. What evidence you graciously provide generally appears less than solid, as I’ve picked apart most of it. A few misuses of terminology here and there do not constitute the kinds of systemic issues you claim exist.
And this was one example of hundreds I don’t consider worth finding and listing, because it would be too much effort.
If you don’t actually want to find the “hundreds” of examples you claim that exist, then you don’t want the problem to be fixed. You want to complain. You’re like the person who calls tech support because he’s having a problem with his computer, but the only information he provides is “it doesn’t work.”
So my question for you is this: do you just want to complain and get stuff off your chest? Or do you want to actually get something substantive changed in the spec? Because complaining won’t actually do that; years watching this forum prove that. If you have specific grievances, file bugs on them (not that this guarantees anything of course). If you refuse to find specific grievances and just want to say, “rewrite the whole spec. Again,” then you’re not being part of the solution.
But here, let me just open the reference and pick the first best sentence that I can spot on that page, to show you how easily one finds these “legitimate grievances”:
7.8 Shader Buffer Variables and Shader Storage Blocks: The second sentence (the first one seems all right to me):
“Sets of buffer variables are grouped into interface blocks called shader storage blocks”.
Now let us dissect that seemingly all-right sentence:
“Sets of buffer variables”: Okay. No complaint here. This is the non-ambiguous subject of the sentence.
“are grouped into”: You may not notice it, but that statement (as is the whole sentence) is pointless. What does “grouped” actually mean? Is it something like “they are considered to be part of”? Grouping is not defined anywhere.
… I just want to be clear on this. You are now claiming confusion about the meaning of a plain English word, yes?
Let’s compare this with a sentence from C++11 by analogy:
“tuples are heterogeneous, fixed-size collections of values.”
The terms “heterogeneous”, “fixed-size”, and “collection” are never defined anywhere. However, all of them are in the dictionary (save fixed-size, which is a compound term made from two dictionary terms). So… that’s where you find their definitions. If you don’t know what they mean, you look them up.
“Grouped” is not a “technical term”; it is a word in the English language: “to place or associate together in a group, as with others.” It doesn’t need a definition, just like “sets”, “are”, and “into” don’t. Indeed, you could make the exact same argument against “Sets of buffer variables” by declaring that the word “sets” hasn’t been defined yet. So your singling out of the word “grouped” doesn’t really make sense here.
So let’s substitute the definition into the sentence: “Sets of buffer variables are associated together in a group in interface blocks called shader storage blocks.”
Sadly, failing to use a dictionary does not constitute a “legitimate grievance”.
I’m guessing that your next argument will be that some dictionary words are technical terms (like “bind” and “attach”), while others have their obvious meaning (like “sets” and “grouped”). So let me just head that off.
The specification is quite clear on the meaning of the binding of objects; it has a whole section that introduces the concept (section 2.4). So “bind” is clearly defined and consistently used. While “attach” is used as a technical term, the dictionary definition for the term is sufficient since it is consistently and only used when describing object-to-object linking.
The specification explicitly says that “bind” means “to context”, and it is never used in its dictionary definition. And it never uses “attach” to mean “to context”. So it never needs to come out and explicitly say that “attach” only involves object-to-object linking.
And thus there is no confusion. Well, save for what you make for yourself by asking why it isn’t always called “bind”, even though it’s clearly two different kinds of operations. If you take the spec at face value, there’s nothing to be confused about.
“interface blocks called shader storage blocks”: Now isn’t that lovely. So we have established three terms for the same entity (sets of buffer variables) within one sentence. Even better: Instead of calling those “groups” “buffer variable blocks” or even “buffer variable groups”, we’ve extended our vocabulary by a completely different word. And a huge vocabulary is good, right? It makes you elloquent!
No it isn’t. The point of a specification is not to be elloquent nor to immerge the reader into its fictional world (latter of which the GL spec is extremely guilty of). A specification is supposed to use a minimum of defined terms to achieve a maximum of clarity and non-ambiguity.
Let’s look at this sentence, but instead we’ll replace all of the technical terms with placeholders:
Sets of X are grouped into Ys called Z.
What this sentences says is obvious, regardless of what X, Y, and Z are: it defines a relationship between the three terms. It tells us that there are component parts X, sets of which can be grouped into things called Y. The specific name for such things are called Z.
The relationship between these terms is quite simple: Z is a specialized form of Y. Specifically, it is a Y that is made up of X’s; Y could theoretically be made of other things, but when Y’s are made of X’s, they are called Z’s.
In order for this relationship to exist and be discussed effectively, we must have three terms. We need a term for X, the atomic unit that can be grouped. We need a term for Y, the generalized grouping of things, which could be X’s or something else. We need Y, because we need to be able to talk about all groupings of this kind, whether they contain X’s or not. And we need a term for Z, which is a specialized form of Y that groups only X’s; thus allowing us to talk about this specific kind of grouping.
Therefore, we need a minimum of three terms to talk about this stuff. The specification is therefore using “a minimum of defined terms.” Therefore, by your own definition, the spec is fine on this point.
Now, you can argue that the specification could call “shader storage blocks” by a name more closely related to “buffer variables”. And to be honest, I wouldn’t disagree. However, even if they were called “buffer variable blocks”, that would still be a different defined term from “buffer variable”. It would be more obviously related to “buffer variable blocks”, but it’d still be a different term with a different meaning.
So you wouldn’t be changing the number of defined terms in the specification. You’re just picking different words for them.
And quite frankly… it’s too late for that. Even if the ARB wanted to use the name “buffer variable block”, there are already a half-dozen enumerators called “SHADER_STORAGE_…”. They’re not going to break existing code… well for any reason, but especially not just because someone might have come up with a better name for something.
Also, there is an actual reason why it’s not called “buffer variable block.” Because then you would have to call the buffer object storage for them “buffer variable buffer object.” This is a very odd name, what with the double reuse of “buffer” with two different meanings. Now maybe they should have called “buffer variables” something else, like “shader storage variable”. But then, how do you declare them in GLSL? With the “shader_storage” qualifier? “buffer” is much simpler and shorter.
But ultimately, this is all semantics and irrelevant. It’s just a term. You could argue that one would be easier to learn than the other. But the specification doesn’t pick terminology based on how easy they are to learn. Nor is it wrong for not doing so. As long as the specification consistently uses the same terms for the same concepts, and does not use different terms for the same concept, it’s fine.
There is yet another thing I’d like to add with regard to foward references. It is not occurence of forward references alone, that takes from clarity. It is particularly the way they are made: Casually, mentioning the term has if it had been properly defined or the reader, at this point had already encountered it, where in fact, the first mention of it comes much later. This is in stark contrast to the clean, comprehensible style of the XML specification or even the C++ specification where references are explicit and clearly denoted as such.
Let’s test this theory.
The first use of the term “braced-init-list” in N3337 for C++11 (PDF) is in section 5.2, folio page 93. It states, “A braced-init-list shall not be used with the built-in subscript operator.” The actual definition of this term is in section 8.5.4, folio page 199. The first use of the term “template” is at the start of section 3; it is not actually defined until section 14.
In neither place is there an “explicit” or “clearly denoted” reference to where these terms are defined. Sometimes the C++ specification will provide a section number when referencing a term, and sometimes it won’t.
The only difference is the fact that the C++11 specification italicizes all of its terminology, whereas OpenGL reserves italics almost exclusively for function argument names. If you want to claim that the specification should have some special formatting for all of its technical terms, I wouldn’t disagree. Obviously it can’t be italics, but it could be something else.