search

SMPTE / html-pub

Tools for publishing SMPTE documents as HTML documents
BSD 3-Clause "New" or "Revised" License
1 stars 0 forks source link

Additional Elements Format #213

Open ERyan71258 opened 6 months ago

ERyan71258 commented 6 months ago

Should Additional Elements be listed in a table format?

Clause 6.6 in the AG-16 specifies the following as an example:

"This annex lists non-prose elements of this document."

image

When I use a table to list the elements, I slightly rewrite the introductory sentence; otherwise, the table is not referenced, and per ISO, it should be: "Table .1 lists non-prose elements of this document." or "This annex lists non-prose elements of this document, as shown in Table .1."

palemieux commented 5 months ago

The Additional Elements element of the document should be unnumbered.

ERyan71258 commented 2 weeks ago

If the Additional elements clause is unnumbered, then the AG-16 language introducing the elements must be changed, as the clause is no longer an annex:

"6.6 Non-prose elements of the Engineering Document_ All non-prose elements of the Engineering Document, as defined in AG-02, shall be explicitly referred to within the prose element.

All non-prose elements of the Engineering Document shall be listed in an informative annex titled Additional elements, which shall be the final annex of the document.

This annex shall be introduced by the following sentence: This annex lists non-prose elements of this document.

The list shall include the letter designator, a brief description of the non-prose element, and an indication of whether the non-prose element is normative or informative."

"This annex lists non-prose elements of this document." would require rewording.

Even though the "Additional elements" clause is informative, each item listed must also be specified as either "normative" or "informative", as there may be a mix (e.g., ST 2021-4)

If restoring an annex letter to the "Additional Elements" heading, then the annex must be referenced from the body text. It should be referenced in any case.

palemieux commented 2 weeks ago

@ERyan71258 Please open the issue in AG-16: https://github.com/smpte/ag-16

ERyan71258 commented 2 weeks ago

Reopening to address language inconsistency and conflict with the AG-16.

Also referenced this issue in https://github.com/SMPTE/ag-16/issues/35