Metanorma NIST document attributes
Document attributes listed below are unique to the processing of IEEE SA documents in Metanorma.
For common document attributes, see Document attributes reference in general Metanorma author's documentation. That page describes attributes that apply to all Metanorma flavors, not just IEEE SA.
For an introduction to Metanorma AsciiDoc document attributes and how Metanorma uses them, see the corresponding topic.
See /flavors/nist/ref/notes/ for identifier-composition rules, series guidance, and document-relationship conventions.
Document information
:edition:
The document version; e.g. 2.0.
:revdate:
The date the document was last updated.
:copyright-year:
The year which will be claimed as when the copyright for the document was issued.
:title-main:
The main component of the title of the document (mandatory). If absent, the first line of the AsciiDoc document, which contains the title introduced with =, is used.
:uri:
The URI to which this standard is published.
:status:
Document status/stage. The permitted types are:
draft-internaldraft-wipdraft-prelimdraft-publicdraft-approvalfinal(default: document is published)final-review
draft-internalInternal NIST draft.
draft-wipWork-in-progress draft.
draft-prelimPreliminary draft.
draft-publicPublic draft.
draft-approvalDraft in approval.
finalFinal (default: document is published).
final-reviewFinal, in review.
:substage:
Document substage. Indicates active status of draft or publication. If a draft or publication is inactive, that is reflected in the coverpage. The permitted types are:
active(default)retired(applies only to drafts, when they are abandoned). The:abandoned-date:must
be provided, to indicate when the draft was abandoned.
withdrawn(applies to drafts, when when they are superseded by the next draft stage,
and to published documents when they are superseded or no longer valid.
activeActive (default).
retiredRetired (applies only to drafts, when they are abandoned).
:abandoned-date:must be provided, to indicate when the draft was abandoned.withdrawnWithdrawn (applies to drafts superseded by the next draft stage, and to published documents superseded or no longer valid).
:language:
enTwo-letter code (ISO 639-1) of the language the document is written in. Defaults to en. If multiple languages are used in the document, comma-delimited; e.g. en,fr.
The following document attributes are specific to NIST:
:title-sub:
The subtitle of the document.
:title-main-short:
Shortened form of the title of the document. For use in Word header. If not provided, :title-main: is used.
:title-sub-short:
Shortened form of The subtitle of the document. For use in Word header. If not provided, :title-sub: is used.
:title-document-class:
The title of the document class that the document belongs to; e.g. "Computer Security" for SP 800.
:keywords:
Comma-delimited list of the keywords associated with the document.
:iteration:
The iteration of a stage, in case there have been multiple drafts. Can be a number, or text (e.g. "initial", "final").
:doctype:
standardStandard (the only NIST document type).
Inherited from Metanorma (all flavors) (23 attributes)
:publisher{_i}:
The standards agency publishing the standard. NOTE: Prior to 1.7.0, this field accepted comma-delimited values. NOTE: Prior to 2.7.0, this field accepted semicolon-delimited values. These are processed via CSV, recognising quote marks. This functionality is maintained in later versions, but other attributes of organisations are ignored (publisher_logo, pub-address, etc.)
:publisher_abbr{_i}:
The abbreviation of the publisher; if not provided, and the standards organisation is the home organisation of the standard, the SDO's abbreviation will already be available to Metanorma, and will be supplied.
:publisher_logo{_i}:
The path to the logo of the publisher, specified as an image file; the numbers in the attribute align to the :publisher{_i}: attributes.
:sponsor{_i}:
An organization sponsoring the publication of this document. NOTE: If a person needs to be nominated as the responsible party for a sponsoring organization, that person should be treated as a personal contributor (:surname{_i}:, :affiliation{_i}:, etc.), with a :role: attribute of enabler.
:sponsor_logo{_i}:
The path to the logo of the sponsoring organization, specified as an image file; the numbers in the attribute align to the :sponsor{_i}: attributes.
:copyright-holder:
The copyright holder, if distinct from the publisher; can be multiple (semicolon-delimited: processed via CSV, recognising quote marks).. NOTE: Prior to 1.7.0, this field accepted comma-delimited values.
:docidentifier-additional:
This attribute provides additional primary identifiers for the document, to be used alongside the native identifier generated from docnumber or docidentifier. It is intended for copublished standards with multiple primary identifiers. The list of identifiers is comma-delimited, and is specified as TYPE:VALUE; e.g. :docidentifier-additional: IDF:IDF 21, RFC:RFC 97.
:library-ics:
The ICS (International Categorization for Standards) number for the standard. There may be more than one ICS for a document; if so, they should be comma-delimited. (The ICS identifier is added to the document metadata, but may not be visible in the resulting document, depending on Metanorma flavor.)
:isbn:
The ISBN-13 number of the document. This value is optional.
:isbn10:
The ISBN-10 number of the document This value is optional.
:title:
The title of the document. If not supplied, the built-in AsciiDoc title (first line of document header) is used instead.
:title-{langcode}:
The title of the document in the language langcode. langcode is a ISO 639-1 code.
:title-en:, :title-fr:
:title-{type}-{langcode}:
The title of the document in the language langcode, and of type type.
The title of the document in the language langcode, and of type type. Note: this was previously supported only in individual flavours.
:title-main-en:, :title-intro-fr: + NOTE: This was previously supported only in individual flavours that required title parts, such as ISO that supports main, intro, part, complementary, addendum. It is now supported generically in Metanorma.
:doctype-abbrev:
The document type abbreviation; e.g. TN for "technical note". Can be used in document metadata, e.g. cover page. .
:docsubtype:
The document subtype; by default, used to provide an ad hoc, user defined document class, unless provided for explicitly in the flavour, as in OGC
:docstage:
:docstage-abbrev:
The document stage abbreviation; e.g. D for "draft". Can be used in document metadata, e.g. cover page. .
:docstage-published:
Whether the current document stage should be considered as published. Boolean. If not provided, and if there is no setting specific to the flavor, the default is that only the stage "published" is considered published.
:docstage-valid:
Comma-delimited list of the statuses recognised as valid for this document, superseding the flavour's own repertoire in status validation. Normally set by a Metanorma taste rather than by authors: a taste that defines its own stages advertises through this attribute the base stages it maps them to, so that the underlying flavour does not report them as unrecognised.
:docsubstage:
The substage code for the document status, where applicable.
:classification:
Comma-delimited list of classification tokens, expressed as type:value pairs; if no prefix is given to a value, "default" is supplied as the type. There can only be one value per type in a token; if there are multiple classification values of the same type, repeat the type in a new token; e.g. :classification: Dewey:563.5.081, Dewey:537.71.
:draft:
If present, reviewer notes will be rendered (otherwise those are suppressed). Is also ued as a legacy equivalent of :version:.
:document-scheme:
Document content arrangement that Metanorma will enforce for this document. Accepted values are flavour-specific. Depending on the document scheme, Metanorma may insert clauses with predetermined text and orders clauses in accordance with the style prescribed by the SDO. If those styles are updated, this attribute indicates to Metanorma which iteration of the prescription to enforce. NOTE: As of this writing, implemented in the IEEE, BSI, ITU and ISO flavours.
Document identifier
:docnumber:
The internal identifier referring to this document. The identifier is a number; the prefix, e.g. "NIST SP", is supplied by the :series: attribute. The NIST identifier is docnumber-edition (if edition is present)
:docidentifier:
The document identifier for the document. Normally this should not be supplied, as the document identifier is composed from the document series, document number, document volume, and edition/revision (e.g. NIST SP 800 Revision 1).
If the :docidentifier: value is provided, it will override this composed value.
CSWP publications do not have a distinct :docidentifier: or :docnumber:: they are identified by their :issued-date:.
The following document attributes are specific to NIST:
:revision:
The document revision; e.g. 1 (Revision 1). Will be stored in Metanorma XML under the <edition> tag, with the prefix Revision .
:version:
The document version, when titled as version. Will be stored in Metanorma XML under the <edition> tag, with the prefix Version . It is also being treated as the <version><draft> version, consistent with the rest of Metanorma.
:volume:
The number of the volume of a standard. Is ignored if a precomposed document identifier (:docidentifier:) is supplied. Is prefixed with "Volume" or "Vol." in display.
:part:
The part number of a standard. Is only used to generate machine readable NIST identifier (nist-mr).
:section:
The section number of a standard. Is only used to generate machine readable NIST identifier (nist-mr).
:supplement:
The supplement number of a standard. Is only used to generate machine readable NIST identifier (nist-mr). Can be supplied with an empty value to indicate that this is a supplement of a standard.
:index:
The index number of a standard. Is only used to generate machine readable NIST identifier (nist-mr). Can be supplied with an empty value to indicate that this is an index of a standard.
:update:
The update number of a standard. Is only used to generate machine readable NIST identifier (nist-mr).
:addendum:
The document is an addendum to a document. Used to generate machine readable NIST identifier (nist-mr), and to style document as addendum.
:doi:
DOI URL for document (distinct from :uri:, which is the URL that NIST publishes the document under.)
Document series
:series:
The publication series that the document belongs to. Legal values are given as the keys of the pubid-nist series listing. For legacy purposes, nist-* is converted to NIST * in all caps; and nist-cswp (Cybersecurity White Papers) is converted to the correct CSRC White Paper. nist-csts is also supported as an ad hoc series.
Documents belonging to different series are expected to be rendered differently. As of this writing, styling has been provided for nist-cswp (Cybersecurity White Papers), nist-csts (Cybersecurity Technical Specifications), and for nist-sp (SP-800).
:series-title:
(Added in v1.2.10)
:series-mrprefix:
(Added in v1.2.10)
:series-abbrev:
(Added in v1.2.10) The formal documents published by NIST belong to a registered list of series, each with a predefined title and abbreviation. Non-formal documents instead belong to ad hoc series defined for the purposes of Metanorma, such as nist-csts. That particular series acts as an umbrella for user-defined series of publications; so when it is used, the user needs to provide a title (e.g. "Automated Cryptographic Validation Protocol") and abbreviation (e.g. ACVP) for the user-defined series. The user also needs to provide the prefix by which the series will be identified in the machine-readable NIST identifier, when it is at variance with the abbreviation. In this case, CSTS is retained as the primary series of the publication (and all CSTS documents are rendered the same way), and ACVP is modelled as a secondary series specific to CSTS. However, the series information rendered for the document involves the user-defined series, not CSTS itself.
Document dates
:issued-date:
The date on which the document was authorised to be published. Referred to within NIST as the "Publication Date". This is the date used on the document cover page. Only applies to public documents; drafts instead have a :circulated-date: attribute.
:published-date:
The publication date for the document, when it was physically released. Referred to within NIST as the "Release Date". This date is not used on the document cover page; :issued-date: is used instead. The Release Date is included in NIST bibliographic metadata.
:obsoleted-date:
The date at which a document is considered no longer valid (withdrawn). If a document is not currently withdrawn (as indicated through :substage: withdrawn), but will be in the future, that is still indicated in the rendering of the document.
:confirmed-date:
The date at which a document has been reviewed according to the NIST ERB 5-year review process, and has been confirmed to be relevant and valid to date. If this attribute is present, the date is included in the cover page.
:updated-date:
The date at which a document has been updated without being considered a distinct new publication. Used to indicate the date of errata releases.
:circulated-date:
The date at which a draft is circulated. Displayed on the cover page of drafts. MANDATORY FOR DRAFTS.
The following document attributes are specific to NIST:
:comment-from:
The beginning of the period during which comments may be submitted to the NIST document draft. ISO-8601 date.
:comment-to:
The end of the period during which comments may be submitted to the NIST document draft. The end of the period may change, and may be left open-ended (omitted). ISO-8601 date.
:comment-extended:
The date on which the during which comments may be submitted to the NIST document draft was extended.
:superseded-date:
The date at which both this document and the document superseding it come into effect, as a transition period before this document is withdrawn. May be identical to :obsoleted-date:, in which case there is no such transition period. Is indicated in withdrawn publication cover page; if not provided, the value of :obsoleted-date: is given.
:abandoned-date:
The date at which work on a document is abandoned. At that date, the document is considered retired (substage: retired). In NIST, only drafts may be retired. If the document is not currently retired (as indicated through :substage: retired), but will be in the future, that is still indicated in the rendering of the document.
Document relationships
:merges:
This document incorporates the document(s) with the nominated identifiers (semicolon-delimited).
:updates:
This document is an update of the document(s) with the nominated identifiers (semicolon-delimited).
The following document attributes are specific to NIST:
:obsoletes:
One or more NIST document that this NIST document standard renders obsolete; implies that the obsoleted document is withdrawn, and no longer in effect. Comma delimited. Format is document identifier, e.g. SP 800-53A Rev. 1
:obsoleted-by:
One or more corresponding NIST document that this NIST document standard is obsoleted by; requires that this document is withdrawn, and no longer in effect. Comma delimited. Format is document identifier, e.g. SP 800-53A Rev. 1. Is the relation between a withdrawn draft, and the next draft in the approval process.
:supersedes:
One or more NIST document that this NIST document standard supersedes; the superseded document may still remain in effect. Comma delimited. Format is document identifier, e.g. SP 800-53A Rev. 1
NOTE: The distinction between obsoletes and supersedes is the withdrawal date of the original document (obsoleted-date); that means that the distinction is predictable given that external information. The distinction between obsoleted-by and superseded-by, in the same way, is made by the withdrawal date of the current document. Relaton does not differentiate between the two relations for that reason.
:superseded-by:
One or more corresponding NIST document that this NIST document standard is superseded by; this document may still remain in effect. Comma delimited. Format is document identifier, e.g. SP 800-53A Rev. 1 Is not the relation between a withdrawn draft, and the next draft in the approval process (since the earlier draft is automatically no longer in effect).
Document contributors
:technical-committee:
The name of the relevant committee producing the document.
:fullname{_i}:
The full name of a person who is a contributor to the document, their organization, and the address of that person or organization. In NIST, only the city is given as the address. A second person is indicated by using a numeric suffix: :fullname:, :fullname_2:, fullname_3:, &c. The same convention applies to all the following attributes.
:affiliation{_i}:
The organizational affiliation of a person who is a contributor to the document.
:address{_i}:
The organizational address of a person who is a contributor to the document.
The following document attributes are specific to NIST:
:surname{_i}:
The surname of a person who is a contributor to the document.
:givenname{_i}:
The given name(s) of a person who is a contributor to the document.
:initials{_i}:
The initials(s) of a person who is a contributor to the document.
:role{_i}:
The role of a a person who is a contributor to the document. By default, they are coded as an editor; they can also be represented as an author.
:nist-division:
Name of NIST division responsible for document. Added to authority statement as document contact, and to coverage of withdrawn published document. Default value is "Computer Security Division, Information Technology Laboratory".
:nist-division-address:
Address of NIST division responsible for document. Added to authority statement as document contact. Use line breaks (in AsciiDoc: + \) if necessary. Default value is "100 Bureau Drive (Mail Stop 8930) Gaithersburg, MD 20899-8930"
:doc-email:
Email contact for document
:sponsor:
The name of the organization that has sponsored the document, if applicable. The attribute can contain multiple lines and Metanorma formatting.
:sponsor-logo:
The logo of the sponsoring organization, if applicable.
Superseding document appearance
:superseding-status:
Document status/stage of the superseding document, if this document is superseded or withdrawn. Used for withdrawn drafts. Used for withdrawn published documents, if an entry for the superseding document is not available on the CSRC website (where it can be retrieved through the :obsoleted-by: document attribute.)
:superseding-iteration:
The iteration of the stage of the superseding document, in case there have been multiple drafts. Can be a number, or text (e.g. "initial", "final"). Used for withdrawn drafts.
:superseding-title:
The title of the draft document superseding this document. If not supplied, the current title is assumed to have been retained. Used for withdrawn drafts. Used for withdrawn published documents, if an entry for the superseding document is not available on the CSRC website (where it can be retrieved through the :obsoleted-by: document attribute.)
:superseding-subtitle:
The subtitle of the draft document superseding this document. If not supplied, the current subtitle is assumed to have been retained. Used for withdrawn drafts. Used for withdrawn published documents, if an entry for the superseding document is not available on the CSRC website (where it can be retrieved through the :obsoleted-by: document attribute.)
:superseding-circulated-date:
The date at which the draft document superseding this document is circulated. Used for withdrawn drafts.
:superseding-issued-date:
The date at which the document superseding this document was authorised to be published. Used for withdrawn published documents, if an entry for the superseding document is not available on the CSRC website (where it can be retrieved through the :obsoleted-by: document attribute.)
:superseding-doi:
The DOI of the document superseding this document. Used for withdrawn drafts. Used for withdrawn published documents, if an entry for the superseding document is not available on the CSRC website (where it can be retrieved through the :obsoleted-by: document attribute.)
:superseding-url:
The URL of the document superseding this document. Used for withdrawn drafts. Used for withdrawn published documents, if an entry for the superseding document is not available on the CSRC website (where it can be retrieved through the :obsoleted-by: document attribute.)
:superseding-authors:
The authors of the superseding document. Comma-delimited. Used for withdrawn published documents, if an entry for the superseding document is not available on the CSRC website (where it can be retrieved through the :obsoleted-by: document attribute.)
:bib-additional-note:
Additional note (optional), used on coverpage of withdrawn and retired drafts, and as "Related Information" on coverpage of withdrawn published documents.
:bib-withdrawal-note:
Withdrawal note, used on coverpage of withdrawn published documents.
:bib-withdrawal-announcement-link:
Hyperlink to announcement of withdrawal, used on coverpage of withdrawn published documents.
Visual appearance
:call-for-patent-claims:
Include the Call for Patent Claims in document drafts, and the Patent Disclosure Notice in finalised documents. (Not applicable to CSWP.)
:commitment-to-licence:
Indicate in the Patent Disclosure Notice that notice and commitment to license have been received. (Not applicable to CSWP.)
:patent-contact:
Contact for the Call for Patent Claims or Patent Disclosure Notice. If not supplied, :doc-email: is used. (Not applicable to CSWP.)
:biblio-as-appendix:
By default, bibliographies are treated as separate from appendixes in output: they are published in front of any appendixes. This is the prescribed behaviour for NIST documents moving forward. If present, bibliographies are treated in the legacy manner: they are treated like appendixes, and are given an appendix number according to where in the document they occur.
:boilerplate-authority:
Build and configuration
Inherited from Metanorma (all flavors) (8 attributes)
:document-class:
The flavor of Metanorma used to compile the document; e.g. iso, nist, ogc. Needs to be a supported version of the document.
:flavor:
:output-extensions:
The output formats to generate for the document, comma-delimited; e.g. xml,presentation,html,doc,pdf. The formats supported vary for each flavor, but all flavors support xml (Semantic XML), presentation (Presentation XML), and one of html or pdf.
:imagesdir:
(Optional) Directory in which images are located: all local image file locations are prefixed with this directory. Accepts a directory path.
:nodoc:
Instructs Metanorma to not generate Word and HTML output, means only XML output will be generated.
:novalid:
Suppress document validation.
:index-terms:
Terms (and symbols) are indexed automatically in postprocessing. See automatic terms indexing.
:relaton-output-file:
Output the bibliographic record describing the document as a Relaton XML file (with the suffix .rxl).
Bibliography
Inherited from Metanorma (all flavors) (11 attributes)
Reference lookup
:no-isobib:
If set, do not use the relaton or iev gem functionality to look up ISO and IEV references online, nor the cache of relaton and iev searches.
Publication date cutoff
:bibliography-cutoff-date:
Override the publication date used for the bibliographic cutoff, instead of deriving it from the document's own date attributes. Accepts a date (YYYY, YYYY-MM, or YYYY-MM-DD); the value none (or false) disables the cutoff entirely, so references resolve to their latest editions and current status.
Caching
:no-isobib-cache:
If set, use the relaton and iev gem functionality to look up ISO and IEV references online, but do not use the cache of relaton and iev searches.
:local-cache:
Use the local Relaton and iev search caches to override the global relaton and iev search caches. If a directory name is given for the attribute, that name overrides relaton as the cache name.
:local-cache-only:
Use the local Relaton and iev search caches to the exclusion of the global relaton and iev search caches. If a directory name is given for the attribute, that name overrides relaton as the cache name.
:flush-caches:
If set, delete and reinitialise the cache of Relaton searches.
:relaton-data-source:
Allows specification of an external bibliographic file to be imported. The value of the field is the file name. If the format also needs to be specified, this is done as file=PATH/TO/FILE,format=FORMAT. Valid formats are follows.
bibtexThe BibTeX format. Currently, only this is supported as a format, all other formats will raise an error.
:relaton-data-source-{id}:
Allows specification of multiple external bibliographic files to be imported. The different bibliographic sources are differentiated through the value of the {id} identifier.
:relaton-data-source-bib1: PATH/TO/FIRST/FILE
:relaton-data-source-bib2: PATH/TO/SECOND/FILEReference sort order
:sort-biblio:
If set to false, do not sort the bibliography; references are left in document order. Sorting is on by default.
Sort bibliographies in the document according to criteria set by the flavor Default: true. .
:sort-biblio-{abbrev}:
Override the publisher sort ranking for the bibliography, one attribute per publisher. The attribute-name suffix {abbrev} is the publisher's abbreviation; the value is the sort rank (lower sorts earlier) followed by the publisher's full name, separated by a colon ({rank}: {name}). A reference is matched to a publisher by its abbreviation (case-insensitive) or its name; matched publishers sort in the given rank order, followed by other standards, then other references. This is the mechanism a Metanorma taste uses to set a house bibliographic sort order: the taste configuration compiles to these document attributes. Because they are ordinary document attributes, an author can equally set them directly in a single document to override the sort order for that document alone.
:sort-biblio-OIML: 1: International Organization of Legal Metrology
:sort-biblio-ISO: 2: International Organization for Standardization
:sort-biblio-IEC: 3: International Electrotechnical CommissionReference rendering
:relaton-render-config:
Override the default configuration of Relaton Render selectively, with attributes from the named configuration YAML file. See Relaton Render specification for description of the configuration file format. We recommend you inspect the configuration compiled into the flavor gem (lib/relaton/render/config.yml) and include modifications of that in the override config file.
Math and scientific formatting
Inherited from Metanorma (all flavors) (6 attributes)
:keep-asciimath:
Do not translate Asciimath in the document to MathML.
:suppress-asciimath-dup:
By default, MathML in the Metanorma XML has equivalent AsciiMath added to it in a comment. This AsciiMath can be used as an accessibility alternative to the MathML expression. The generation of this AsciiMath can be suppressed.
:stem:
asciimath(Defaults to asciimath) The default language for stem:[...] and [stem] blocks expressions in the document. (AsciiMath, MathML, or LaTeX). For example, if you want the stem expressions in your document to be interpreted as LaTeX by default, use :stem: latexmath.
Read more about mathematical expressions.
:number-presentation:
Sets the formatting options for the number:[] command in the document. Please refer to the dedicated section at numbers for usage.
:number-presentation: attribute:number-presentation: notation=e,exponent_sign=plus,precision=4number:341[]
:number-presentation-profile-{NAME}:
Sets the formatting options for the number:[] command in the document as profile {NAME}. Please refer to the dedicated section at numbers for usage.
:number-presentation-profile-{NAME}: attribute:number-presentation-profile-3: notation=scientific,exponent_sign=nil,decimal=","number:342[profile=3]
:number-presentation-formula:
Sets the formatting options for numbers contained in formulas. Please refer to the dedicated section at numbers in formulas.
Languages and localization
Inherited from Metanorma (all flavors) (4 attributes)
:i18nyaml:
Name of YAML language template file. Use if you wish to output an standard in a language that's not supported out of the box. For more on how to customize localization, see Localization.
:script:
LatnThe script of the document (ISO 15924). Defaults to Latn. Must be supplied as Hans for Simplified Chinese.
:locale:
The locale of the document (currently expected to be a two-letter country code, ISO 3166-1 alpha-2).
:localize-number:
Template for how to present localized numbers. The localization template string is in the following form: :localize-number: +++#,##0.### ###+++ TIP: See Number localization for how numbers are localized in Metanorma.
Generic metadata
Inherited from Metanorma (all flavors) (11 attributes)
:semantic-metadata-{name}:
Comma-delimited list of values, relating to name as semantic metadata about the document. Stored in the document under //metanorma-extension/semantic-metadata/{name}, with repeating tags for each value.
:presentation-metadata-{name}:
Comma-delimited list of values, relating to name as presentation metadata about the document. Stored in the document under //metanorma-extension/presentation-metadata/{name}, with repeating tags for each value.
The following instances of generic metadata are applicable to all flavors of Metanorma; other instances are specific to flavors, and are documented there:
:semantic-metadata-headless:
This document is to be compiled without adding initial document boilerplate to it. This is used for compiling Metanorma AsciiDoc boilerplate documents themselves.
:presentation-metadata-doctype-alias:
Specify how the document type is to be rendered. This overrides the language-specific internationalization of the supplied document type, and is used in Metanorma tastes, to override the base flavor document type rendering.
:presentation-metadata-custom-charset-font:
Specify a custom character set for Unicode "Private Use Area" (PUA) character codepoints
presentation-metadata-publisher-{doc|html|pdf}-{width|height}[{_i}]
Specify height and width of the publisher logo, for each of the standard output formats of Metanorma. The publishers are read in the same sequence for logo attributes as they are for publisher names and abbreviations, and the numbering includes the primary publisher of the document as the first publisher (for which a logo typically does not need to be specified.)
For example, presentation-metadata-publisher-pdf-height_2 specifies the height of the coverpage logo in PDF of the second specified publisher.
:presentation-metadata-ul-label-list:
Specify the characters to be used as bullets for unordered lists, as a comma-delimited list of strings, each string corresponding to a deeper level of list. The bullet list rotates once the list is exceeded. NOTE: Custom unordered list bullets are only processed for PDF output.
:presentation-metadata-ul-label-list: *,–,"x,x" will use * at level 1; – at level 2, x,x at level 3, then go back to * at level 4.
:presentation-metadata-annex-delim:
Delimiter between the line heading giving the number of an annex, and the title of the annex (Metanorma XML, default <br/><br/>) .
:presentation-metadata-middle-title:
Presentation XML Liquid template for middle title (document title at the start of the main section of the document) (Metanorma XML, default "<p class='zzSTDTitle1'>{{ doctitle }}</p>") . Refer to Default metadata values for the typical values that can be used in metadata-driven Liquid templates under Metanorma.
:presentation-metadata-admonition-icon-{type}:
Add the Unicode character as an icon in front of the label for all admonitions of type {type}; overrides any value given in admonition-icon under the i18n internationalization file . If the admonition type contains spaces, replace them with underscores in the attribute name: an admonition of type Safety Precautions is matched by :presentation-metadata-admonition-icon-safety_precautions: .
:presentation-metadata-html-details-open:
Whether the details element in HTML (used for collapsible examples) should be open or closed for HTML documents. Defaults to true, and corresponds to <details open="open"> vs <details>. .
Document relations
Inherited from Metanorma (all flavors) (2 attributes)
Part of
:part-of:
document identifier that the current document is a part of.
Translated from
:translated-from:
document identifier that the current document is a translation of.
URIs
Inherited from Metanorma (all flavors) (5 attributes)
:xml-uri:
The URI to which the (Metanorma) XML representation of this standard is published.
:html-uri:
The URI to which the HTML representation of this standard is published.
:pdf-uri:
The URI to which the PDF representation of this standard is published.
:doc-uri:
The URI to which the DOC representation of this standard is published.
:relaton-uri:
The URI to which the Relaton XML representation of this standard is published.
Timestamps
Inherited from Metanorma (all flavors) (9 attributes)
:announced-date:
The date on which the publication of the standard was announced by the issuing authority.
The date on which the document was announced as forthcoming.
:implemented-date:
The date on which the standard became active.
:created-date:
The date on which the first version of the standard was created.
:corrected-date:
The date on which the current version of the standard was corrected, without that correction amounting to a distinct update.
:unchanged-date:
The date on which the standard was last renewed without any changes in content.
:accessed-date:
The date on which the standard was last accessed by the compiler of the bibliography; e.g. for a cited online resource, the date on which the document author viewed the resource.
:date:
An arbitrary date in the production of the standard. Content of the attribute should be a token, giving the type of date, then space, then the date itself. Multiple dates can be added as :date_2:, :date_3:, etc.
:vote-started-date:
The date on which the voting process starts for this document.
:vote-ended-date:
The date on which the voting process ends for this document.
Author information
Inherited from Metanorma (all flavors) (44 attributes)
:technical-committee_{1}:
The name of the relevant editorial group. The document attribute name for editorial groups varies by flavor, and there can be multiple types of editorial group, each with its own document attribute; see Contributor metadata: Groups for the value for each flavor.
In the following list, technical-committee can be replaced by each of the allowed editorial group labels; for example, if workgroup is an editorial group label, then :workgroup-label: and :workgroup-type: are document attributes, instead of :technical-committee-label: and :technical-committee-type:.
:technical-committee-number{_i}:
The identifier of the editorial group.
:technical-committee-type{_i}:
The type of the editorial group. Typically this is used as the abbreviation prefixed to the editorial group number.
:technical-committee-number: 2, :technical-committee-type: TC, giving TC 2.
:technical-committee-agency{_i}:
The agency that the editorial group lies under, if it is other than the home agency (the publisher of the document). Only needed for multiple editorial groups.
:technical-committee-agency-abbr{_i}:
The abbreviation of the agency that the editorial group lies under. In most flavors, the abbreviation of the SDO is already available for lookup in Metanorma, and users need not provide this attribute.
For example, under metanorma-iso, :technical-committee-agency: can be specified as ISO, rather than needing to specify both :technical-committee-agency: International Standardization Organization and :technical-committee-agency-abbr: ISO.
:technical-committee_logo{_i}:
The logo of the editorial group, specified as an image file.
:committee-types:
Comma-delimited list of committee types to be recognized for the document. Overrides the preset committee types set for the flavor. .
:corporate-author{_i}:
The organization authoring the standard. This document attribute **should not** be provided if the authoring organization is identical to the publishing body, as its value is automatically set to that of :publisher:. Use :corporate-author: **only when** a standard is authored or co-authored by an agency distinct from the publishing body, and only the publishing agency is credited as the publisher. Multiple agencies can be specified as corporate authors (similar to :publisher:). The first agency specified is expected to be the publishing body. Use :corporate-author_2:, :corporate-author_3:, etc. for additional agencies. NOTE: For personal authors, use :fullname: or :surname: and :givenname: instead.
:contributor-credentials{_i}:
Credentials of the person, appearing after their name in Metanorma flavour-specific contexts.
The credentials of the person (e.g. "PhD, F.R.Pharm.S"); these are often displayed inline with the person's name.
:role-description{_i}:
A more detailed description of the role of a person who is a contributor to the document.
:affiliation_abbrev{_i}:
The abbreviation of the organization that a person who is a contributor to the document is affiliated with.
:affiliation_subdiv{_i}:
The subdivision of the organization that a person who is a contributor to the document is affiliated with. The subdivisions can be multiple (semicolon-delimited: processed via CSV, recognising quote marks), and they can also be hierarchical, with multiple levels of subdivision (comma-delimited, from larger to smaller) ; the different hierarchical levels can optionally be prefixed with type and a colon.
:affiliation_logo{_i}:
The logo of the organization that a person who is a contributor to the document is affiliated with, specified as an image file.
:contributor-position{_i}:
The position of the person within the organization.
:street{_i}:
The street component of the organization address of a person who is a contributor to the document.
:city{_i}:
The city component of the organization address of a person who is a contributor to the document.
:region{_i}:
The region component of the organization address of a person who is a contributor to the document.
:country{_i}:
The country component of the organization address of a person who is a contributor to the document.
:postcode{_i}:
The postcode component of the organization address of a person who is a contributor to the document.
:contributor-uri{_i}:
The URI of a person who is a contributor to the document.
:email{_i}:
The email of a person who is a contributor to the document.
:phone{_i}:
The phone number of a person who is a contributor to the document.
:fax{_i}:
The fax number of a person who is a contributor to the document.
:subdivision:
The subdivision of the organization that is responsible for this document. The subdivisions can be multiple (semicolon-delimited: processed via CSV, recognising quote marks), and they can also be hierarchical, with multiple levels of subdivision (comma-delimited, from larger to smaller) ; the different hierarchical levels can optionally be prefixed with type and a colon.
:subdivision-abbr:
The abbreviation of the subdivision of the organization that is responsible for this document.
:pub-address{_i}:
The address of the organization responsible for this document, if it overrides the default.. The number of this and subsequent attributes aligns with the number of :publisher{_i}:
Each line in a multi-line address must end with + \, e.g.
:pub-address: 1 Infinity Loop + \
California + \
United States of AmericaNOTE: As of 2.7.0, if :publisher: is semicolon-delimited, instead of using numbered attributes, this and subsequent publisher attributes are ignored.
:pub-phone{_i}:
The phone number of the organization responsible for this document, if it overrides the default.
:pub-fax{_i}:
The fax number of the organization responsible for this document, if it overrides the default.
:pub-email{_i}:
The email of the organization responsible for this document, if it overrides the default.
:pub-uri{_i}:
The URI of the organization responsible for this document, if it overrides the default.
:sponsor-address{_i}:
The address, phone number, fax number, email, URI of an organization sponsoring this document.
:sponsor-phone{_i}:
:sponsor-fax{_i}:
:sponsor-email{_i}:
:sponsor-uri{_i}:
:sponsor-subdivision{_i}:
The subdivision of the organization that is sponsoring this document. The subdivisions can be multiple (semicolon-delimited: processed via CSV, recognising quote marks), and they can also be hierarchical, with multiple levels of subdivision (comma-delimited, from larger to smaller) ; the different hierarchical levels can optionally be prefixed with type and a colon.
:authorizer{_i}:
The organisation that authorised this document.
:authorizer_logo{_i}:
The path to the logo of the authorizing organization, specified as an image file; the numbers in the attribute align to the :authorizer{_i}: attributes .
:authorizer-address{_i}:
The address, phone number, fax number, email, URI of an organization authorizing this document.
:authorizer-phone{_i}:
:authorizer-fax{_i}:
:authorizer-email{_i}:
:authorizer-uri{_i}:
:authorizer-subdivision{_i}:
The subdivision of the organization that is authorizing this document. The subdivisions can be multiple (semicolon-delimited: processed via CSV, recognising quote marks), and they can also be hierarchical, with multiple levels of subdivision (comma-delimited, from larger to smaller) ; the different hierarchical levels can optionally be prefixed with type and a colon.
Style customization
Inherited from Metanorma (all flavors) (27 attributes)
Fonts
:fonts:
Semicolon-delimited listing of fonts to be used for this document, in addition to the fonts predefined for the flavour.
Valid values are font names supported by Fontist. The full font name listing is available from the Fontist Formulas repository.
NOTE: This is currently only used in PDF generation.
The Euphemia font is an openly licensed font for end-users only commonly used to render Canadian Syllabics. The font name Euphemia is supported by Fontist for unattended install. In a document that contains Canadian Syllabics, the following attributes can be used.
:fonts: Euphemia
:font-license-agreement: agree-to-terms:font-license-agreement:
The response to the license agreement prompt by fontist for the fonts specified in :fonts:.
Valid values are:
no-install-fonts(default) do not install any additional fonts, even when listed in
:fonts:.agree-to-termsagree to all terms of the fonts that will be installed in an unattended manner.
continue-without-fontsdo not warn if a font is not available on the system.
:body-font:
Font for body text; will be inserted into CSS, overriding the default set for the particular Metanorma flavour.
:header-font:
Font for headers; will be inserted into CSS, overriding the default set for the particular Metanorma flavour.
:monospace-font:
Font for monospace; will be inserted into CSS, overriding the default set for the particular Metanorma flavour.
HTML
:html-stylesheet:
SCSS stylesheet to use for HTML output. Defaults to built-in stylesheet for the particular Metanorma flavour. Overriding is not recommended.
:html-stylesheet-override:
CSS stylesheet to use for HTML output, inserted after the built-in stylesheet for the particular Metanorma flavour, and can be used to override it.
:html-cover-page:
HTML template for cover page. Defaults to built-in template for the particular Metanorma flavour. Overriding is not recommended.
:html-intro-page:
HTML template for introductory section. Defaults to built-in template for the particular Metanorma flavour. Overriding is not recommended.
:scripts:
JavaScript scripts for HTML output. Defaults to built-in scripts for the particular Metanorma flavour. Overriding is not recommended.
:scripts-override:
JavaScript scripts for HTML output. Inserted after any built-in scripts for the particular Metanorma flavour, and can be used to override them.
:scripts-pdf:
JavaScript scripts for HTML to PDF output. Defaults to built-in scripts for the particular Metanorma flavour. Overriding is not recommended.
:presentation-metadata-papersize:
PDF document page size. Can be used to override the page size in built-in stylesheet for the particular Metanorma flavour. Valid values are: Letter, letter, A4 or a4.
LetterletterA4a4
:pdf-stylesheet:
XSLT stylesheet to use for PDF output. Defaults to built-in stylesheet for the particular Metanorma flavour. Overriding is not recommended.
:pdf-stylesheet-override:
XSLT stylesheet to use for PDF output, inserted after the built-in stylesheet for the particular Metanorma flavour, and can be used to override it.
Word
:word-stylesheet:
Primary SCSS stylesheet to use for Word output. Defaults to built-in stylesheet for the particular Metanorma flavour. Overriding is not recommended.
:standard-stylesheet:
Secondary SCSS stylesheet use for Word output. Defaults to built-in template for the particular Metanorma flavour. Overriding is not recommended.
:word-stylesheet-override:
CSS stylesheet to use for Word output, inserted after the built-in stylesheet for the particular Metanorma flavour, and can be used to override it.
:header:
Header and footer file for Word output. Defaults to built-in template the particular Metanorma flavour. Overriding is not recommended.
:word-cover-page:
Word template for cover page. Defaults to built-in template for the particular Metanorma flavour. Overriding is not recommended.
:word-intro-page:
Word template for introductory section. Defaults to built-in template for the particular Metanorma flavour. Overriding is not recommended.
:ulstyle:
Word CSS selector for unordered lists in supplied stylesheets. Defaults to value for built-in stylesheet. Overriding is not recommended.
:olstyle:
Word CSS selector for ordered lists in supplied stylesheets. Defaults to value for built-in stylesheet. Overriding is not recommended.
Cover page
:coverpage-image:
Comma-delimited list of image locations, for images to be included on the (PDF) cover page. All image locations are relative to the source document. Currently only supported for BSI, ITU, JIS, Plateau. If the supplied image(s) is to replace the cover page(s) of the document in its entirety, and already includes title information, add the attribute :presentation-metadata-full-coverpage-replacement: true (supported for all flavours).
:innercoverpage-image:
Same, for images to be included on the (PDF) inside cover page. Currently only supported for BSI.
:tocside-image:
Same, for images to be included on the (PDF) Table of Contents side page. Currently only supported for BSI.
:backpage-image:
Same, for images to be included on the (PDF) back page. Currently only supported for BSI, JIS.
Image handling
Inherited from Metanorma (all flavors) (5 attributes)
Data URI
:data-uri-image:
Encode all images in Metanorma XML and HTML output as inline data-URIs. Defaults to true..
:data-uri-maxsize:
Set the maximum permitted size of a Data URI-encoded image, in bytes. Defaults to 13981013 bytes (size of the Base-64 encoding of a 10 MB image). If set to 0, no maximum is enforced..
:data-uri-attachments:
Encode all attachments in Metanorma XML as inline data-URIs. Defaults to true..
SVG
:svg-conform-profile:
Profile of the 0 software library to apply for SVG validation and repair. See SVG Profiles for the available profile values. Metanorma by default uses the metanorma profile by default, except for IETF, which uses svg_1_2_rfc.
PlantUML
:plantuml-image-format:
Format to generate PlantUML diagrams as. Legal values are png, svg. Defaults to png..
pngsvg
Cross-references
Inherited from Metanorma (all flavors) (5 attributes)
:xrefstyle:
Override the default rendering style of internal cross-references to other locations in the document. Available styles as follows:
short(default) the clause type and number is used as the cross-reference.
Example of a cross-reference rendered in the "short" style"Clause 3.1.2"
basicthe title of the clause is used as the cross-reference.
Example of a cross-reference rendered in the "basic" style"Other considerations"
fullcombines the title with the clause type/number cross-reference.
Example of a cross-reference rendered in the "full" style"Clause 3.1.2, Other considerations"
idmetanorma-standoc ≥ v2.2.7the cross-reference is to be rendered as the target anchor identifier (or any identifier aliasing the anchor).
Example of a cross-reference rendered in the "id" styleThe following cross-reference:
[[my-anchor]] === My title ... === Another place <<my-anchor>>Renders the cross-reference as:
"my-anchor"
:erefstyle:
Override the default rendering style of cross-references to bibliographic entries . The legal values for such override are drawn from General citation style types.
:originstyle:
Override the default rendering style of source references to bibliographic entries . The legal values for such override are drawn from General citation style types.
:modspec-identifier-base:
(optional) Base identifier pattern for ModSpec instances throughout the document. The attribute value provides a prefix that will be removed from all ModSpec instance identifiers used to cross-reference ModSpec instances. The specification of the pattern only affects the rendering of cross-references, not the underlying XML representation of the ModSpec instances. See more details at ModSpec identifier base.
:block-unnumbered:
(optional) A comma-delimited list of Metanorma block names, which should have numbering suppressed throughout the document. Typically will be used for sourcecode fragments: :block-unnumbered: sourcecode.
Smart quotes
Inherited from Metanorma (all flavors) (1 attributes)
:smartquotes:
trueApply “smart quotes” and other auto-formatting to the XML output (and hence the downstream outputs). Available values below:
"and'followed by space, with optional punctuation intervening, are treated as closing,
and converted to smart closing quotes ” and ’.
"and'preceded by space, with optional punctuation intervening, are treated as opening,
and converted to smart opening quotes “ and ‘.
- Midword apostrophes are treated as closing:
Sana'abecomesSana’a. - Initial apostrophes before numerals are treated as closing:
'80sbecomes’80s. - There are many possible exceptions to these default rules, such as initial apostrophes
(fish ’n’ chips), and quote pairs used to illustrate the punctuation (Use smart quotes (" ")). For such cases, use either real smart quotes (the literal characters “ ” ‘ ’) or the Asciidoc ASCII codes, "` `", '` `'
The smart quotes converted by Metanorma postprocessing are specifically those of English. Other languages' smart quotes will need to be entered as the correct characters.
NOTE: :smartquotes: is a document-wide toggle. To keep specific runs of text as straight quotes while the rest of the document remains smart-quoted — for example, literal characters quoted from a specification, such as PDF string-delimiter operators — use 1 .
true(default) Smart quotes are not applied to the following type of text:
- text in source code;
- text in pseudo-code;
- text in monospace.
falseThe AsciiDoc default is used to generate smart quotes:
"` `",'` `'. The rules for smart formatting follow the sterile gem, and are given in smart_format_rules.rb. In particular:
Table of contents
Inherited from Metanorma (all flavors) (8 attributes)
:toclevels:
2Number of table of contents levels to render. Accepts an integer value. (default: 2). Can be overridden with output-specific options (htmltoclevels, doctoclevels).
:toclevels-html:
Number of table of contents levels to render in HTML output; used to override :toclevels: for HTML output. Accepts an integer value. (default: 2). Formerly :htmltoclevels:.
:toclevels-doc:
Number of table of contents levels to render in Microsoft Word "DOC" output; used to override :toclevels: for Word DOC output. Accepts an integer value. (default: 2). Formerly :doctoclevels:.
:toclevels-pdf:
Number of table of contents levels to render in PDF output; used to override :toclevels: for PDF output. Accepts an integer value. (default: 2)
:toc-figures:
Introduce table of contents for figures. No attribute value needed. Only numbered and/or captioned figures are included. Disabled if given the value false.
:toc-tables:
Introduce table of contents for tables. No attribute value needed. Only numbered and/or captioned tables are included. Disabled if given the value false.
:toc-examples:
Introduce table of contents for examples. No attribute value needed. Only numbered and/or captioned examples are included. Disabled if given the value false.
:toc-requirements:
Introduce table of contents for requirements, recommendations, and permissions. No attribute value needed. Only numbered and/or captioned requirements, recommendations, and permissions are included. Disabled if given the value false.
Tables
Inherited from Metanorma (all flavors) (1 attributes)
:break-up-urls-in-tables:
If present, long strings in table cells are broken up on rendering, to help tables fit within the page width. No attribute value needed.. The current behaviour is: strings are broken by zero-width spaces; words are broken up every 10 characters on punctuation (e.g. URIs on / ), and every 20 characters if there is no punctuation in the word, in order to deal with very narrow columns. (Because the break is zero-width, it will not be visible unless it coincides with the end of a column.)
Sourcecode
Inherited from Metanorma (all flavors) (6 attributes)
:sourcecode-markup-start:
Initial delimiter for markup inserted in sourcecode
:sourcecode-markup-end:
Final delimiter for markup inserted in sourcecode
:source-highlighter:
Whether to use a source highlighter for sourcecode; default value is true
:source-linenums-option:
Provided a source highlighter is being used, whether to display line numbers; default value is false
:bare:
(optional) The document is rendered in “bare form” -- without the cover page, boilerplate, or introductory text expected of a complete document. This is typically used for HTML output, e.g. clauses as standalone documents, or document attachments.
:base-asset-path:
(optional) All media paths in the XML path are relative to the given directory; used when the Metanorma XML file to be processed is not necessarily in the same directory as the source Metanorma AsciiDoc file, and the media file paths are given as relative and not absolute file locations (and are not encoded as data URIs via :data-uri-image:).
Logging
Inherited from Metanorma (all flavors) (3 attributes)
:log-filter-severity:
Filter from error log all warnings at the given severity level or above it. See Validation for valid values.
:log-filter-category:
Filter from error log all warnings belonging to one of the named categories; comma-delimited. See Validation for valid values.
:log-filter-error-ids:
Filter from error log all warnings with the identifiers of individual errors to exclude (comma-delimited). See Error ID. .
PDF protection and permissions
Inherited from Metanorma (all flavors) (13 attributes)
:pdf-encrypt:
falseSpecify encryption of PDF output.
trueApplies encryption to PDF output.
falseDo not encrypt PDF output. (default)
:pdf-encryption-length:
256Specify encryption strength.
256Use 256-bit AES keys (default)
128Use 128-bit AES keys.
:pdf-user-password:
Specify user password needed to open the encrypted PDF document. The attribute value sets the user password.
:pdf-owner-password:
Specify owner password to bypass restrictions on encrypted PDF document. The attribute value sets the owner password.
:pdf-allow-copy-content:
trueAllow content to be copy-pasted from the PDF document.
trueContent can be copy-pasted from the PDF document. (default)
falseContent cannot be copy-pasted from the PDF document.
:pdf-allow-edit-content:
trueAllow content of the PDF document to be edited.
trueContent of the PDF document can be edited. (default)
falseContent of the PDF document cannot be edited.
:pdf-allow-assemble-document:
trueAllow inserting, deleting, or rotating pages in the PDF document.
trueInserting, deleting or rotating pages in the PDF document is allowed. (default)
falseInserting, deleting or rotating pages in the PDF document is disallowed.
:pdf-allow-edit-annotations:
trueAllow annotations and signatures to be added to the PDF document.
trueAnnotations and signatures can be added to the PDF document. (default)
falseAnnotations and signatures cannot be added to the PDF document.
:pdf-allow-print:
trueAllow PDF document to be printed, physically or to a file.
truePDF content can be printed, physically or to a file. (default)
falsePDF content cannot be printed, physically or to a file.
:pdf-allow-print-hq:
trueAllow PDF document to be printed in high quality.
truePDF content can be printed in high quality. (default)
falsePDF content cannot be printed in high quality.
:pdf-allow-fill-in-forms:
trueAllow forms to be filled in the PDF document.
trueForms in the PDF document can be filled in. (default)
falseForms in the PDF document are read-only, they cannot be filled in.
:pdf-allow-access-content:
trueAllow text and graphics extraction from the PDF document for accessibility purposes.
trueText and graphics can be extracted from the PDF document. (default)
falseText and graphics cannot be extracted from the PDF document.
:pdf-encrypt-metadata:
trueSpecify encryption of the metadata stream.
trueThe PDF metadata stream will be encrypted. (default)
falseThe PDF metadata stream will not be encrypted.