SMPTE AG 02
Administrative Guideline
Document Naming and Packaging
Draft - Tue Dec 06 2022 00:52:15 GMT+0000 (Coordinated Universal Time)
SMPTE (the Society of Motion Picture and Television Engineers) is an internationally-recognized standards developing organization. Headquartered and incorporated in the United States of America, SMPTE has members in over 80 countries on six continents. SMPTE’s Engineering Documents, including Standards, Recommended Practices, and Engineering Guidelines, are prepared by SMPTE’s Technology Committees. Participation in these Committees is open to all with a bona fide interest in their work. SMPTE cooperates closely with other standards-developing organizations, including ISO, IEC and ITU. SMPTE Engineering Documents are drafted in accordance with the rules given in its Standards Operations Manual.
This Standards Administrative Guideline forms an adjunct to the use and interpretation of the SMPTE Standards Operations Manual. In the event of a conflict, the Operations Manual shall prevail.
Copyright © The Society of Motion Picture and Television Engineers.
This Administrative Guideline defines the numbering format for SMPTE Engineering Documents and specifies the permitted file formats used during document development and publication. It also specifies other matters relating to SMPTE Engineering Documents with regard to language, style, format, document type, markups required at various stages of development, etc.
Files that show the differences between two versions of the same document are called "markups" in this Administrative Guideline. "Markup" is intended to cover a variety of terms including: "redline," "tracked changes," "blackline," etc.
Normative text is text that describes elements of the design that are indispensable or contains the conformance language keywords: "shall", "should", or "may". Informative text is text that is potentially helpful to the user, but not indispensable, and can be removed, changed, or added editorially without affecting interoperability. Informative text does not contain any conformance keywords.
All text in this document is, by default, normative, except: the Introduction, any section explicitly labeled as "Informative" or individual paragraphs that start with "Note:"
The keywords "shall" and "shall not" indicate requirements strictly to be followed in order to conform to the document and from which no deviation is permitted.
The keywords, "should" and "should not" indicate that, among several possibilities, one is recommended as particularly suitable, without mentioning or excluding others; or that a certain course of action is preferred but not necessarily required; or that (in the negative form) a certain possibility or course of action is deprecated but not prohibited.
The keywords "may" and "need not" indicate courses of action permissible within the limits of the document.
The keyword "reserved" indicates a provision that is not defined at this time, shall not be used, and may be defined in the future. The keyword "forbidden" indicates "reserved" and in addition indicates that the provision will never be defined in the future.
Unless otherwise specified, the order of precedence of the types of normative information in this document shall be as follows: Normative prose shall be the authoritative definition; Tables shall be next; then formal languages; then figures; and then any other language forms.
The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
No terms and definitions are listed in this document.
All SMPTE Engineering documents shall be written in U. S. English. Translations into other languages by SMPTE (or by 3rd parties authorized by SMPTE) are encouraged but not required. In the event of discrepancy, the original English language document shall be authoritative.
All Engineering Documents should follow the guidelines of the International Organization for Standardization (ISO) Directives with the following exceptions: In the event of a conflict, explicit provisions of SMPTE Standards Operations Manual and Administrative Guidelines shall prevail. Any variances from the ISO Directives shall be approved by the Director of Engineering or the Standards Vice President.
Particular attention should be given to the following annexes of the ISO Directives, Part 2:
The ISO Directives are available at: http://www.iso.org/directives.
All new Engineering Documents shall use the appropriate, approved SMPTE template. (See Administrative Guideline AG-04 Engineering Document Templates.) This will ensure proper revision management through and including final publication. Document templates can be found in the Standards Community document repository.
A revision of an Engineering Document may use the original template if the resulting prose is identical to that resulting from use of the current template and the Standards Vice President or Director of Engineering agree to the use of the original publication template.
For a revision of an Engineering Document, the Project Group should start with the Publication Master, which usually can be obtained from SMPTE HQ. The Project Group may, at its discretion, recreate the original document, as published, if an editable master cannot be found. The Project Group is encouraged to follow the ISO Directives but is under no obligation to do so.
An Amendment shall use the current template.
SMPTE Engineering Documents may be published on paper or in various electronic formats and may comprise one or more separate elements. An Engineering Document always shall include a single prose element and may include other elements such as XML, spreadsheets, media files, and so forth. The collection of elements, regardless of formats employed, is the "Engineering Document" as a whole, and all elements shall be clearly identified in the prose element (see 10.4). Any change to any element constitutes a change to the Engineering Document. The Project Group and the Technology Committee shall determine the number of elements for publication. The Director of Engineering shall determine the distribution media for all published documents. The format of publication shall alter neither the relevance of, nor the processes that otherwise are required for approval of, an Engineering Document.
Engineering Document Elements may be packaged as one or more Elements using ZIP to facilitate the organization and distribution of the component files.
Engineering Documents and other contributed documents shall be submitted to a Technology Committee or its subgroups in a limited set of file formats. The following formats are approved:
doc and .docx
Engineering Documents should use Office 2007 formats (.docx) for Prose and tabular documents. Engineering Documents may use Office 2003 formats (.doc) as needed. The Project Group shall determine which format to use on a project-by-project basis. Conversions between Office 2003 and Office 2007 formats are not perfect. To minimize the risk of unintended artifacts, conversion between formats is not required.
(.pdf)
Adobe Acrobat files may be contributed but shall be accompanied by editable files for all the elements in the document (prose, tables, drawings, etc.) to permit further revision.
.xls and .xlsx
The Project Group shall decide which spreadsheet format (.xls or .xlsx) to use for each project. The preferred format is .xlsx.
Any document conforming to W3C Extensible Markup Language (XML) 1.0 (Fifth Edition) or W3C Extensible Markup Language (XML) 1.1 (Second Edition) may be submitted.
The namespaces of all normative XML elements used in XML documents shall have a corresponding normative reference in the prose.
The file extension shall be ".xml", unless otherwise specified by the defining specification of the document or by an appropriate IANA media type registration.
Documents conforming to the following XML-based specifications are specifically allowed:
.vsd, vsdx, .dwg and .emf
For new projects .jpg, .jpeg, .png, .tif and .tiff are approved image formats. Revisions of existing documents may continue to use .bmp.
Any audio, video or image media format documented by SMPTE, whether in an Engineering Document or an RDD, or any other media format that is commonly used, widely available, and appropriate for the user community for which the Engineering Document has been created.
.txt and program source formats
The Director of Engineering shall store and process documents in the format chosen by a Project Group and/or Technology Committee. The Director of Engineering shall ensure that copies of the editable source documents are maintained for all published Engineering Documents. The editable publication master should be made available by the Director of Engineering when a Revision or Amendment project is started.
Normative information in a SMPTE Engineering Document may take the language form of prose, tables, figures, formal languages (e.g., mathematical formulae, BNF, XML, pseudo code), and other language forms. Mathematical formulae shall follow the definitions documented in ISO 80000-2 when possible. When ISO 80000-2 is not sufficient (e.g., BNF, XML Schema, etc.), a Normative Reference for the mathematical definitions used shall be provided. Such Normative Reference shall comply with the provisions of the SMPTE Standards Operations Manual and AG-03 Normative References.
When language forms other than prose are present, the prose shall state whether the language is normative or informative. Normative provisions shall be enabled explicitly (e.g., "The dimensions of figure 1 shall be used."). The presence of non-prose information without prose conformance language shall be deemed informative.
In accordance with ISO 8601-2004, all dates shall be represented in the form YYYY-MM-DD as numeric digits (e.g. 2009-04-23 to indicate April 23, 2009).
Document numbers shall be unique and uniform across all Engineering Document types. Versions of documents shall be identified by their year of publication and, optionally, their month of publication, appended with a separating colon (e.g., for document #1020: 1020:2009 or 1020:2009-04, the latter indicating publication in April, 2009). Figure 1 shows an example of the document numbering structure.
The Director of Engineering shall assign document numbers (or root document numbers, in the case of multipart documents). Document numbers may be assigned at the request of the Technology Committee Chair(s) at any time after a Project is approved and shall be assigned before a Final Committee Draft ballot is issued.
Older Engineering Documents may bear one-, two-, or three-digit document numbers or root document numbers. These numbers shall not be prepended with leading zeroes when formatted for printing, either in the document itself or in citations in other documents. Such document numbers shall be prepended with leading zeroes to fill them out to four digits, however, when used as part of an element’s filename; the purpose is to facilitate sorting into numerical order.
The Type of Engineering Document (Standard, Recommended Practice or Engineering Guideline) shall be denoted by prepending a Type Designator, followed by a single space, to the document’s root number. The Type Designator shall be as follows:
Although they are not Engineering Documents, Registered Disclosure Documents, Advisory Notes, Administrative Guidelines, and Engineering Reports shall bear Type Designators as follows:
RDDs and ERs shall be numbered using independent number spaces. The numbers shall be assigned by SMPTE Headquarters staff.
Closely related Engineering Documents may be created as Parts. A Part of a document is a separate Engineering Document and shall be shown to be related to other
by using the same root document number plus a suffix of a hyphen and the Part number to distinguish among Parts (e.g. 1020-2:2009, indicating document 1020, Part 2).
A multipart set of documents may include Parts of different types of Engineering Documents, including Standards, Recommended Practices, and Engineering Guidelines. Each Part’s number shall include the appropriate document type designation (e.g. RP 2046-2:2009).
A multipart set of documents should be supplemented by an informative Part 0, informally described as an “Overview Document,” which shall describe the relationships among the Parts and may describe the relationships of the Parts to other Engineering Documents. Part 0 documents are not due process Engineering Documents;
Part 0 documents usually should be prepared by the authors of the related engineering documents in cooperation with SMPTE headquarters staff and the responsible Technology Committee and Project Group. Part 0 documents shall be maintained by the Director of Engineering in consultation with the Technology Committee Chair(s) and the author(s) of the Part 0 document. If new Parts are added to a multipart set, or if any of the Parts of the set are revised, Part 0 shall be revised at the same time. The Part 0 designation shall not be used for any Engineering Document. Part 0 documents shall not bear a Type designator (i.e. it is not an ST, RP or EG).
A Part 0 document should not contain forward-looking statements in regard to documents that are not ready for publication.
As a general guideline, Part 0 documents should use the following structure:
Examples of Part 0 documents: SMPTE 2052-0 or SMPTE 425-0.
Normative references to multipart documents always shall specify the individual Part or Parts being referenced and shall not reference the entire set by root number alone.
Non-prose Elements of Engineering Documents (see 7) shall be designated using a lower case
letter (e.g. 1020a:2009 and 1020b:2009). Media such as DVDs, as well as non-PDF formats, shall be clearly marked, as appropriate. The single prose element shall not receive aletter suffix.
All new Engineering Documents shall share a common root number space, starting with 2000, except for new Parts of multipart documents that have a one-, two- or three-digit root.
In the past, each type of Engineering Document had its own number space. This presented difficulties when a Technology Committee determined that the document type had to be changed (for example, changing a Recommended Practice to a Standard) if the number in the new number space already was in use. To address this going forward, the block of numbers from 1000 to 1999 has been allocated.
If a Technology Committee determines that the classification of an Engineering Document with a one-, two- or three-digit root must be changed (e.g., from a Recommended Practice to a Standard) and there already is an Engineering Document with that number, the document whose classification is being changed shall have 1000 added to its root. For example, if the Technology Committee were to determine that Recommended Practice RP 222 should be changed to a Standard, its number would be changed to SMPTE ST 1222 because there already is a SMPTE ST 222.
Each of the other published document types (i.e., Registered Disclosure Documents, Advisory Notes, Administrative Guidelines, and Engineering Reports) shall have its own number space independent of Engineering Documents and of each other. They otherwise shall follow the rules for document numbering specified in this Administrative Guideline.
File names for due process Engineering Documents should be constructed as follows.
<group> “-“ <state> “-“ <type> “-“ <number> [ “-“ <part> ] [ <element> ] “-“ <description> “-“ <date> [ “(“ <note> “)” ] “.” <extension>
Where:
<group><state><type><number><part><element><description><date><note><note> shall be constructed using only alpha characters, digits, “-“.<extension>NOTE —
The <description> and <note> fields can use CamelCase or hyphens as word separators. The Document Editor and Project Chair need to consider both choices and make a decision based on the project name, any acronyms used, the length of the name and related factors.
The Project Group should follow the recommendation in this section or the requirements in 10. The final publication name shall be assigned by the Director of Engineering.
Elements that are a collection of files shall be aggregated into a single file that is a .zip file. The .zip file may contain other .zip files if necessary. The file name for the .zip file shall follow the rules outlined in 11.2. The names of the files in the .zip file shall be at the discretion of the Project Group. The Project Group may use the schemes defined in this AG. They should use a scheme that is appropriate for the files in the element.
File names for contributions that are not Engineering Documents shall be at the discretion of the individual or group making the contribution. The scheme in 11.1 should be considered as a useful model. If these rules are used, the <state> should be “C.”
For a new project, the document number and even the project short name may not be known. In this event, individuals making the contributions should use their judgment when naming files.
Various document packages are needed during the development process. In all cases, a document being reviewed or voted upon shall be the current draft which is the “clean” version.
In the event that any of the following is in conflict with the SMPTE Standards Operations Manual, the SMPTE Standards Operations Manual shall prevail.
6 of this AG has guidance for the use of templates for new projects, Revisions and Amendments.
For Revisions the process of converting an old document into the current template changes section numbering and alters the appearance of the original document, even though the content of the document has not changed. In this case, it is recommended that the conversion to the current template should be made before any other changes are made. The document editor should “accept all changes” to create a clean starting point (the “baseline draft”) from which to track the technical and/or editorial revisions to the document.
During Working Draft development (an informal process), a Project Group may provide intermediate draft documents and markups for review within the Project Group. Intermediate document packages may include an informal Comment Resolution Record or a Comment Resolution Document.
The state of these draft documents shall be “WD.” Project Groups should follow the recommendations and styles given in this Administrative Guideline for file names.
The first step in the formal document process is the preparation of a Working Draft, which shall be marked as “WD.” This document a package is provided by the Project Group to the Technology Committee Chair(s). This review is optional; See SMPTE Standards Operations Manual for guidance.
The document package shall contain a clean draft. In addition it may contain one of the following:
Following Pre-Ballot Review, a Project Group should address all comments. See the comment resolution process in SMPTE Standards Operations Manual. When the Project Group agrees that the document is ready for ballot, it shall provide a Committee Draft ballot package marked as “CD” to the Technology Committee Chairs(s) that contains:
When additional Final Committee Draft Ballot(s) are required, the Project Group shall submit a package to the Technology Committee Chair(s) that contains the following:
NOTE — If a document passes Final Committee Draft ballot with no comments, comment resolution, Pre-DP Review and a Draft Publication Vote are not required. See SMPTE Standards Operations Manual for guidance.
Incremental Comment Resolution within the Project Group may result in the need for multiple Drafts, Markups, and Comment Resolution Records or Comment Resolution Documents. These document packages shall contain:
When Comment Resolution has been successfully completed, a Pre-DP Review follows. Comment resolution may include one or more Disposition Votes. See SMPTE Standards Operations Manual for guidance.
Following comment resolution, the Project Group shall provide the Technology Committee Chair(s) a Pre-DP review package that contains:
Following the Pre-DP Review, the Project Group shall provide the Technology Committee Chair(s) a DP Vote package that contains:
After a successful DP vote the Draft Publication Vote Package documents shall not be edited by the Project Group participants or the Technology Committee Chair(s) with the exception of changing the document status. If new editorial issues are found, these should be documented and given to SMPTE HQ (see 12.9.)
This document package is the responsibility of the Technology Committee Chair(s) and shall contain:
The Technology Committee Chair(s) shall provide a document package to SMPTE HQ that includes:
NOTE — After each document achieves a successful ST Audit, SMPTE staff will prepare it for publication. The Technology Committee Chairs(s), Project Group Chairs(s) and Document Editor(s) who are responsible for the document are expected to review and approve it before publication.
Registered Disclosure Documents (RDDs) are not Engineering Documents. The RDD approval process includes a Technology Committee Ballot, Comment Resolution and an ST Audit.
Using the content and form of the appropriate Engineering Document packages is recommended.