Open ERyan71258 opened 1 year ago
@ERyan71258 See https://doc.smpte-doc.org/st429-2-private/main/#sec-terms-and-definitions for an example.
Partway there. All terms must be numbered, as they must be able to be referenced. We have not stated a term, and used the abbreviation or the expanded version as its definition.
Example of a term that is defined by its expanded version: Digital Cinema D-Cinema
Example of a term that is defined by its abbreviation: D-Cinema Package DCP
There should be actual definitions. The above two terms could instead be listed in an abbreviated terms list.
The following are closer to what they should be, although they still need to be numbered: International Standard Audiovisual Number ISAN [SOURCE: IETF RFC 4246]
Unique Material Identifier UMID [SOURCE: SMPTE ST 330]
Universally Unique Identifier UUID [SOURCE: IETF RFC 4122]
eXtensible Markup Language XML [SOURCE: W3C XML 1.0]
Pertaining to the above four terms:
eXtensible Markup Language XML whatever the W3C definition is
[SOURCE: W3C XML 1.0]
We could make a case, however, for eliminating the definition and allowing your format, as it is less prone to error and neater.
Some specific issues I see with the "Terms and definitions" clause, based on https://www.iso.org/sites/directives/current/part2/index.xhtml#_idTextAnchor208
'Terminological entries shall be numbered' -- currently they are not
Do you know why ISO requires terms to be numbered since the term itself is what is cited in the main body?
Notes in Terms currently seem to be handled in the same way as all other Notes yet:
I am not a big fan of "notes to entry", esp. when they are used to convey requirements. Is it essential/useful for SMPTE to support?
For each term, there is a cited source, but no definition.
@ERyan71258 This is true when an acronym is defined.
@ERyan71258 See note 1 to entry at https://doc.smpte-doc.org/st429-5-private/44ea72674f08696682194b6eb6d7307ce49867c5/
@ERyan71258 reading https://www.iso.org/sites/directives/current/part2/index.xhtml#_idTextAnchor208 it states:
Terms and definitions should be listed according to the hierarchy of the concepts (i.e. systematic order). Alphabetical order is the least preferred order.
I read that order of usage in the document. Agree?
No and yes. No: I read it as a hierarchy in which a higher-level term encompasses one or more lower-level terms. This is the only area in which I break the admonition against having only one subheading under a heading, as a higher-level term may encompass only one lower-level term.
Examples from ST 2117-1 VC-6. I was document co-editor for this standard. We defined a large number of new terms. We created headings for the categories then listed the terms and their definitions within them:
Example of only one sub-term:
Yes: If the order that they appear in the standard matches the hierarchy, then Yes.
I added a clause before the T&Ds, which should most likely be moved either after the T&Ds, or to an annex in a future revision. It features a table with the terms listed in alphabetical order, with links to their definitions.
We need to clean up references to terms in other documents. I have found that the a referenced term is not always listed in the referenced document T&Ds.
It is possible that it is defined within the body of the referenced document; however, that leaves the reader either wondering why no one confirmed that the term is defined in the referenced document, or having to search the document to see if the term is defined within the body of the document. There should be no uncertainty in a standard.
As a best practice, all terms should be defined within the T&Ds.
One project we should undertake is to map all of the T&D and normative reference dependencies, ensure that they are valid, and create a master list of T&Ds.
One project we should undertake is to map all of the T&D and normative reference dependencies, ensure that they are valid, and create a master list of T&Ds.
That might be something we can automate actually, as Terms (if T&D clause or within the body text) are all wrapped (at least supposed to be) with <dfn>
tags. It could then show which clause they are defined in and link to that.
As in link each use of the term within the document to its definition? That could work.
I was thinking beyond the document itself, e.g., when a term in the T&Ds references the definition of a term in another document, that should be mapped. It would also include the terms in any normatively referenced document.
Create a master list of all terms and definitions in all SMPTE standards documents, specifying the originating documents and dependencies on the original documents. If there are duplicate terms with differing definitions, then they are entered as separate terms, specifying the originating documents.
Dependencies would be specified:
Create a master list of all terms and definitions in all SMPTE standards documents, specifying the originating documents and dependencies on the original documents. If there are duplicate terms with differing definitions, then they are entered as separate terms, specifying the originating documents.
OOOOOOoOoooo. I really like this idea. I could really use this in my registry, scraping all dfn
s and creating a master list to validate against, and automate references as needed. Obviously this is more of a long term goal at the moment, but we can certainly start within the documents.
And also create a map of normative reference dependencies, and even informative (Bibliography) dependencies.
The normative reference chain can become complex. Having a clear record can simplify documentation. Case in point: I am in the 35PM DG IMF Application VC-5 drafting group (headed by Brian Schunck). Lars has considerably simplified the document by pointing out the document contained content that was already specified in the normative references.
I would not be surprised to find circular references in both the T&D dependencies and the document dependencies.
References to non-SMPTE documents should be included as well.
IEEE provides a link to Google Scholar, from which we can search for citations of our documents. That would be a very cool thing to add.
And also create a map of normative reference dependencies, and even informative (Bibliography) dependencies.
I have this all already. See https://stevellamb.github.io/mediastandards-registry/index.html#SMPTE.ST429-2.2020 and https://stevellamb.github.io/mediastandards-registry/dependancies/index.html#SMPTE.ST429-2.2020 for examples. I need to get the new documents in.
Yes, now you are touching on my master plan for my registry and my not-at-all-hidden agenda I have explained to both Pierre and David. :)
Hi Steve,
Excellent! We are so in need of this.
One small tweak: "Dependancies" is misspelled. Should be "Dependencies." [image: image.png]
If not already included, perhaps add a circular reference detector and citation generator.
The Terms and Definitions dependencies would follow a similar model and also provide a master list of T&Ds.
Please feel free to tap me for input/feedback/testing.
All the best,
Ellen
On Fri, May 24, 2024 at 12:56 PM Steve LLamb @.***> wrote:
And also create a map of normative reference dependencies, and even informative (Bibliography) dependencies.
I have this all already. See https://stevellamb.github.io/mediastandards-registry/index.html#SMPTE.ST429-2.2020 and https://stevellamb.github.io/mediastandards-registry/dependancies/index.html#SMPTE.ST429-2.2020 for examples. I need to get the new documents in.
Yes, now you are touching on my master plan for my registry and my not-at-all-hidden agenda I have explained to both Pierre and David. :)
— Reply to this email directly, view it on GitHub https://github.com/SMPTE/html-pub/issues/117#issuecomment-2129995330, or unsubscribe https://github.com/notifications/unsubscribe-auth/A4KXDEHJFHS3JB3R6OFV7UDZD5WMXAVCNFSM6AAAAAAZJZYO2GVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCMRZHE4TKMZTGA . You are receiving this because you were mentioned.Message ID: @.***>
Terms and Definitions shall be formatted as in the following samples: 3.1
picture