KhronosGroup
Convert from tables to sections for builtins.
This Cl changes the builtin functions to use titles sections and code blocks instead of tables. This spaces things out a bit more and fixes issues where there was wrapping in the function declarations due to the size of the table columns.
Note, this depends on https://github.com/KhronosGroup/GLSL/pull/254 to have access to the GLSL syntax highlighting.
For an example:
Before
After
This PR is not yet complete, it's an example of what could be done, if the direction seems appropriate I'll update the rest of the builtin function tables to a similar format.
@gnl21 any thoughts on if this is worth persuing? I'm partial to the non-table layout, but that may just be me. I'm happy to update the rest of the current tables to a similar layout, but don't want to sink the effort if it's a dead end in general.
Looking at this, I think making a change like this will probably make these sections nicer. The current tables are a bit of a mess and, though we could fix some of that, some is caused by trying to fit the functions into half the page, which would be solved by doing something like this. The syntax highlighting and having individual numbers/anchors to refer to the individual functions are also benefits and it solves the problem of having to put LaTeX math outside the tables in sections of its own. I think the main downside is making the chapter much longer, so a bit more difficult to scan through.
The numbering of these sections is different in GLSL/ESSL because of ftransform that doesn't exist in ESSL (or core profile, in fact). Maybe it would be preferable to keep any empty sections like that but not that the functions don't exist so that the numbering and any references from things like extension specs is consistent?
I'm still working through all the builtins (there are a lot of them), so this will take a bit of time before everything is changed over. I'm leaving the numbering as is for now, I'd prefer to do that change to have empty sections as a followup given that this is already going to be a large PR.
I've got all the functions converted at this point. I have to do a read through and compare the new tables to the existing generated GLSL and ESSL specs to verify I didn't mess anything up removing and reformatting things.
K, I think this is ready for review. I didn't add any empty sections to normalize section numbers between GLSL and ESSL at this point, I think that can be done as a followup if we decide to go that route.
@gnl21 can you please give this a review?
Awesome, applied all of the suggestions (and thanks for the careful review, those things are really hard to spot)