I'm worried that there are a couple (at least) of separate requests getting conflated here, and that's causing us to misfire on understanding the work that needs to be done and what its priority is.
First: when you interact with a catalogue through the regular stack API, you have access to the schema, which tells you what all the flags in that catalogue are and provides documentation for them. In other words, you can quite easily pull up a list of flags and other information about a data release which is stored on disk. (Note that at least some of today's confusion emerges from trying to do this not using the stack API but by accessing the persisted FITS files directly. That's much harder, not an interface that we encourage, and not — I think — necessary for what Krzysztof Suberlak was trying to achieve).
Given the above capability, it's (relatively) easy to write an "afterburner" type script for a data release which dumps a web page of all the flag fields that it contains and the associated documentation. If this is really a pressing need, we could go ahead and do it, but I'm not sure that anybody really needs this at the moment. (Of course, when we are generating stable, documented data releases, the need for this is obvious... but currently, we aren't.)
Of course, there's a caveat in the above: not all of the flags have useful documentation (and this, I think, is what winds up John Parejko). Maybe tabulating all of the flags would make that easier to spot, as he suggests. In that case, though, such a table is a means to an end, rather than an end in itself. In any event, badly documented flags count as bugs, and we should file tickets and fix them when we find them.
Now, note that any particular "data release" (or other persisted repository of output data) is the result of executing a particular configuration of the pipelines. That configuration determines exactly which flag fields we actually store. Therefore, a more general — and harder to answer — question than "what flag fields exist in this data release?" is "what flag fields could exist in any conceivable data release?". Jim Bosch gives some thoughts above on how we might go about answering this, but, realistically, I'd question whether this is something worth prioritising.
So that's the story if you're using our API. What if you want to load our FITS data into external tools? Note that this is something we are actually required to support (it's DMS-REQ-0078). Once again, Jim speaks to that above: providing a perfectly generic FITS export of this data is difficult or impossible, and it's of questionable usefulness. That may be a topic we have to return to later in construction, but, at the moment, it's not a priority or something I'd suggest we invest significant resources in.
So where does that get us?
- I hope Krzysztof Suberlak — and any other consumer of a data release — has everything he needs through supported stack APIs, so I don't believe there's actually a crisis here (if not, do shout).
- Badly documented flags deserve bugs, and we'll fix them.
- Dumping HTML catalogues of flags in a data release is certainly something we can do in principle, and will have to for supported data releases, but I question if it's useful in the general case.
- Dumping HTML catalogues of all possible flags is something I'd be reluctant to sign up to unless somebody evinces a really compelling argument (and even then, it'd be serious work).