Policy and/or guidance on labels for Source Code Blocks

[ghobona]

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:

• The asciidoctor-based template supported the use of Listing labels on source code blocks.
• The metanorma-based template offers the use of Figure labels on source code blocks.

Cc: @jechterhoff @ronaldtse

[ronaldtse]

Thanks @ghobona .

Here are some patterns I notice from other SDOs:

In ISO and IEC:

• Source code blocks are considered to be Figures (the only numbered document elements are Figures and Tables)
• If the source code block is considered "inline", they can be unnumbered (i.e. no caption, no number)
• There is an unspoken rule with ISO Editors that unnumbered source code blocks are allowed, but are discouraged

In NIST and ITU:

• Source code blocks are typically unnumbered, and cannot be uniquely referenced.

[jechterhoff]

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.

[ronaldtse]

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:

• legend, keys and labels
• units
• notes
• paragraphs of text

However, I do agree that source code and pseudocode can warrant another label type.

[ogcscotts]

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.

[ogcscotts]

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.

[jechterhoff]

@ogcscotts Is label "Listing" allowed, too?

[jechterhoff]

@ogcscotts Nevermind - I just saw the comment from Gobe, that "Listing" is allowed now.

[ogcscotts]

Document templates need to be updated to reflect this guidance.