Open ghobona opened 1 year ago
Thanks @ghobona .
Here are some patterns I notice from other SDOs:
In ISO and IEC:
In NIST and ITU:
Unnumered code blocks or snippets are certainly needed. In addition, for the more important code blocks, an editor may wish to make them easily accessible - i.e., findable and referenceable, the latter especially when used within the same document. That is why an auto-numbered label is needed, I think.
Thus far, I've seen and used the label "Listing" for such cases. But maybe that is not a commonly accepted writing "style"? When searching on the Web it was hard to find guidance on source code labeling in documents. However, I've come across examples of equations receiving an extra "Equation" label within a scientific document, rather than just being labeled as "Figure". Imho, it would make sense to allow a distinct label for source code blocks in OGC documents, and likewise for other "kinds of things", such as equations.
In most SDOs, e.g. ISO, "Equations" is indeed a type of document element labelled separately. (I clearly missed that in my last comment).
One thing that warrant explanation is that a "Figure" is broader than just an "image". Figures are actually containers that can contain:
However, I do agree that source code and pseudocode can warrant another label type.
will add a topic to the DocTeam to discuss code block and equations and not mandating numbering. There are cases where equations may need to be numbered for reference, so the rule should permit numbering where required for context.
DocTeam 23 April 2024 discussion: recommend that blocks be labelled and inline not labelled, but the recommendation is not formal policy and can be ignored at the editor's discretion.
@ogcscotts Is label "Listing" allowed, too?
@ogcscotts Nevermind - I just saw the comment from Gobe, that "Listing" is allowed now.
Document templates need to be updated to reflect this guidance.
There is a request for DocTeam policy and/or guidance on labels for Source Code Blocks.
https://github.com/metanorma/metanorma-ogc/issues/461
Background:
Cc: @jechterhoff @ronaldtse