Various Locations: Consistency in Language: "This element", The xxx element", etc.; "Element" vs. "Item" - Githubissues

SMPTE / st430-1

Other

0 stars 0 forks source link

Various Locations: Consistency in Language: "This element", The xxx element", etc.; "Element" vs. "Item" #79

Open ERyan71258 opened 7 months ago

ERyan71258 commented 7 months ago

The language starting various clauses should be consistent.

Examples:

6.3.3 CompositionPlaylistId: "This element contains..."
6.3.4 ContentTitleText: "The ContentTitleText element shall contain..."
6.3.5 ContentAuthenticator (Optional): "This element, if present..."

I recommend that they all state the name of the element at the beginning, as in 6.3.4:

6.3.3 CompositionPlaylistId: "The CompositionPlaylistId element contains..."
6.3.4 ContentTitleText: "The ContentTitleText element shall contain..." (Use this as the model))
6.3.5 ContentAuthenticator (Optional): "The ContentAuthenticator (Optional) element, if present..."

Also, 6.3 states: "The KDMRequiredExtensions element shall have the following child elements:" As such, "item" should be replaced by "element" as specified below.

Recommend the following edits:

6.3.3 CompositionPlaylistId: "The CompositionPlaylistId element contains..."
6.3.5 ContentAuthenticator (Optional): "The ContentAuthenticator element, if present..."
6.3.6.1 Overview: "The AuthorizedDeviceInfo item contains..." Change "item" to "element"
6.3.6.2 DeviceListIdentifier: "The DeviceListIdentifier element shall contain..."
6.3.6.4 DeviceList: "The DeviceList item shall contain..." Change "item" to "element"
6.3.7 ContentKeysNotValidBefore: "The ContentKeysNotValidBefore element specifies..."
6.3.7 ContentKeysNotValidAfter: "The ContentKeysNotValidAfter element specifies..."
6.3.9.1 KeyIdList: "The KeyIdList element shall contain..."
6.3.9.1 KeyId: "KeyId elements are...", or, "The KeyId element is a 128-bit UUID that shall be represented in “urn:uuid:” format when it appears as an XML value (IETF RFC 4122)." This fixes a disagreement between plural ("KeyIds" and "when they appear") and singular ("as an XML value").
6.3.10.1 Overview: "When present, the ForensicMarkFlagList element shall contain..."
6.4 NonCriticalExtensions: "The NonCriticalExtensions element is defined..."
7.2.2 KeyInfo: "The KeyInfo element is defined..."

msheby commented 4 months ago

Is one of "the element blah contains" or "the element blah shall contain" preferred to the other?