Document attributes

This is the list of document attributes supported by all flavors of Metanorma.

Tip	If you’re using one of the officially supported flavors of Metanorma, please also see flavor-specific guidance for any additional supported or required document attributes.

Build and validation

: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 reference lookup. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.3]

Reference lookup

For bibliographic lookup, see automatic 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.

Caches

For bibliographic caches, see lookup result 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.

Math

:stem:: This attribute is required if you have any AsciiMath, MathML, or LaTeX included in the document; otherwise they will not be detected. If you want the STEM expressions in your document to be interpreted as LaTeX by default, use :stem: latexmath.

Read more about mathematical expressions.

Languages and localization

Document info

:publisher:

The standards agency publishing the standard; can be multiple (semicolon-delimited: processed via CSV, recognising quote marks). [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.0].

Note	Prior to 1.7.0, this field accepted comma-delimited values [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.1].

:copyright-holder:

The copyright holder, if distinct from the publisher; can be multiple (semicolon-delimited: processed via CSV, recognising quote marks). [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.0].

Note	Prior to 1.7.0, this field accepted comma-delimited values [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.1].

:docnumber:

The numeric component of the document identifier. The full identifier is formed by prefixing and suffixing this element with other strings derived from metadata.

:edition:

The document edition.

:revdate:

The date the document was last updated.

: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 [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.2]

:isbn10:

The ISBN-10 number of the document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.2]

:title:

The title of the document. If not supplied, the built-in AsciiDoc title (first line of document header) is used instead.

:title-XX:

The title of the document in the language XX (where “XX” is a ISO 639-1 code; for example, :title-en:, :title-fr:).

:doctype:

The document type; e.g. "standard", "guide", "report".

: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 [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.1]

:status:

The status of the document; e.g. "draft", "published". Synonym: :docstage:.

:docsubstage:

The substage code for the document status, where applicable.

:iteration:

The iteration of a stage, in case there have been multiple drafts (e.g. 2 on a CD: this is the second iteration through the CD stage).

:keywords:

Comma-delimited list of keywords associated with the document.

: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 [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.1]

:draft:

The document draft. Used in addition to document stage. The value must provide the exact draft iteration in X.Y format (major version number and minor version number separated by a dot). If present, reviewer notes will be rendered (otherwise those are suppressed).

Generic metadata

Metanorma allows generic metadata to be passed to the generated document in key/value form, for downstream use [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.1]. This metadata needs to be indicated as either semantic, or presentation-related. The name of the metadata value is included in the document attribute:

:semantic-metadata-{name}:: Comma-delimited list of values, relating to name as semantic metadata about the document. Stored in the document under //misc-container/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 //misc-container/presentation-metadata/{name}, with repeating tags for each value.

Document relations

General

These attributes takes a document identifier in the Relaton format:

If the document can be found via Relaton auto-fetch (e.g. a published IEC standard), the actual bibliographic item will be used.
Otherwise, a dummy bibliographic item with an empty title and the nominated document identifier will be used.

Multiple document identifiers can be delimited by ;. If the document cannot be auto-fetched, a title for each document nominated can be introduced, delimited from the document identifier by ,. For example, NIST SP 800-1,Title 1;NIST SP 800-2,Title 2.

Part of

part-of: document identifier that the current document is a part of.

This document attribute applies to a document part in order to point to the parent document.

Translated from

translated-from: document identifier that the current document is a translation of.

This document attribute applies to a translated document, pointing to the original (untranslated) document.

URIs

:uri:: The URI to which this standard is published.
: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

:copyright-year:: The year which will be claimed as when the copyright for the document was issued.
:issued-date:: The date on which the standard was issued (authorised for publication by the issuing authority).
:published-date:: The date on which the standard was published (distributed by the publisher).
:implemented-date:: The date on which the standard became active.
:created-date:: The date on which the first version of the standard was created.
:updated-date:: The date on which the current version of the standard was updated.
:obsoleted-date:: The date on which the standard was obsoleted/revoked.
:confirmed-date:: The date on which the standard was reviewed and approved by the issuing authority.
:unchanged-date:: The date on which the standard was last renewed without any changes in content.
:circulated-date:: The date on which the unpublished standard was last circulated officially as a preprint. For standards, this is associated with the latest transition to a formally defined preparation stage, such as Working Draft or Committee Draft.
: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.
:announced-date:: The date on which the document was announced as forthcoming [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.3].

Author info

:technical-committee:

The name of the relevant technical committee.

:fullname{_i}:

The full name of a person who is a contributor to the document. 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. (This and the other personal name attributes are not displayed in all standards.)

: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.

:affiliation{_i}:

The organization that a person who is a contributor to the document is affiliated with.

:affiliation_abbrev{_i}:

The abbreviation of the organization that a person who is a contributor to the document is affiliated with [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.12].

:affiliation_subdiv{_i}:

The subdivision of the organization that a person who is a contributor to the document is affiliated with [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.0]. Can be multiple (semicolon-delimited: processed via CSV, recognising quote marks).

:address{_i}:

The organizational address of a person who is a contributor to the document. Mutually exclusive with street/city/region/country/postcode.

:street{_i}:

The street component of the organization address of a person who is a contributor to the document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.4].

:city{_i}:

The city component of the organization address of a person who is a contributor to the document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.4].

:region{_i}:

The region component of the organization address of a person who is a contributor to the document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.4].

:country{_i}:

The country component of the organization address of a person who is a contributor to the document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.4].

:postcode{_i}:

The postcode component of the organization address of a person who is a contributor to the document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.4].

: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 [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1].

:subdivision-abbr:

The abbreviation of the subdivision of the organization that is responsible for this document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1].

:pub-address:

The address of the organization responsible for this document, if it overrides the default. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1].

Note	Each line in a multi-line address must end with `+ \`, e.g. `:pub-address: 1 Infinity Loop + \ California + \ United States of America`

:pub-phone:

The phone number of the organization responsible for this document, if it overrides the default [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1].

:pub-fax:

The fax number of the organization responsible for this document, if it overrides the default [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1].

:pub-email:

The email of the organization responsible for this document, if it overrides the default [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1].

:pub-uri:

The URI of the organization responsible for this document, if it overrides the default [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1].

Visual appearance

:fonts:

Semicolon-delimited listing of fonts to be used for this document, in addition to the fonts predefined for the flavour [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.7].

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.

EXAMPLE.

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: [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.7].

Valid values are:

no-install-fonts: (default) do not install any additional fonts, even when listed in :fonts:.
agree-to-terms: agree to all terms of the fonts that will be installed in an unattended manner.
continue-without-fonts: do 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.

:htmlstylesheet:

SCSS stylesheet to use for HTML output. Defaults to built-in template for the particular Metanorma flavour. Overriding is not recommended.

:htmlstylesheet-override:

CSS stylesheet to use for HTML output. Is inserted after any built in stylesheet for the particular Metanorma flavour, and can be used to override it. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.8.7]

:htmlcoverpage:

HTML template for cover page. Defaults to built-in template for the particular Metanorma flavour. Overriding is not recommended.

:htmlintropage:

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. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.4]

:scripts-pdf:

JavaScript scripts for HTML to PDF output. Defaults to built-in scripts for the particular Metanorma flavour. Overriding is not recommended.

:wordstylesheet:

Primary SCSS stylesheet to use for Word output. Defaults to built-in template for the particular Metanorma flavour. Overriding is not recommended.

:standardstylesheet:

Secondary SCSS stylesheet use for Word output. Defaults to built-in template for the particular Metanorma flavour. Overriding is not recommended.

:htmlstylesheet-override:

CSS stylesheet to use for Word output. Is inserted after any built in stylesheets for the particular Metanorma flavour, and can be used to override them. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.8.7]

:header:

Header and footer file for Word output. Defaults to built-in template the particular Metanorma flavour. Overriding is not recommended.

:wordcoverpage:

Word template for cover page. Defaults to built-in template for the particular Metanorma flavour. Overriding is not recommended.

:wordintropage:

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.

:data-uri-image:

Encode all images in HTML output as inline data-URIs. Defaults to true. If not provided explicitly, is assumed to be true [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.0].

:smartquotes:

Apply “smart quotes” and other auto-formatting to the XML output (and hence the downstream outputs). Defaults to true.

Smart quotes are not applied to the following type of text:
- text in sourcecode
- text in pseudocode
- text in monospace.
If this attribute is set to false, the 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.

:toclevels

Number of table of contents levels to render (default: 2).

:htmltoclevels

Number of table of contents levels to render in HTML/PDF output; used to override :toclevels: (default: 2).

:doctoclevels

Number of table of contents levels to render in DOC output; used to override :toclevels: (default: 2).

:toc-figures:

Introduce table of contents for figures [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.4]. Only numbered and/or captioned figures are included.

:toc-tables:

Introduce table of contents for tables [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.4]. Only numbered and/or captioned tables are included.

:toc-requirements:

Introduce table of contents for requirements, recommendations, and permissions [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.4]. Only numbered and/or captioned requirements, recommendations, and permissions are included.

:imagesdir

Directory in which images are located: all local image file locations are prefixed with this directory. (Optional.)

:break-up-urls-in-tables:

(for Word output only) If present, long strings in table cells (longer than 30 characters) are broken up on rendering, to help tables fit within the page width [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.25]

Note	Due to limitations of Microsoft Word tables with long string wrapping, this functionality is only applied to Word output [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.29].

: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 [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.5].

:sectionsplit:

(HTML output only) Treat the HTML output as a Metanorma collection, with one web page per clause and annex [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.0].

:sourcecode-markup-start:

Initial delimiter for markup inserted in sourcecode [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.4]

:sourcecode-markup-end:

Final delimiter for markup inserted in sourcecode [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.4]

:bare:

The document is rendered “bare”, without the coverpage, boilerplate, or introductory text expected of a complete standards document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.4]. This is used to compile into HTML e.g. clauses as standalone documents, or document attachments.

:base-asset-path:

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: [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.7].

PDF protection and permissions

All the following attributes relate to PDF protection from copying [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.3].

:pdf-encrypt:: Specify encryption of PDF output. (Allowed values: true, false. Default false.)
:pdf-encryption-length:: Specify encryption strength. (Allowed values: 256, 128, corresponding to 256-bit or 128-bit AES keys. Default 256)
:pdf-user-password:: Specify user password needed to open the encrypted PDF document.
:pdf-owner-password:: Specify owner password to bypass restrictions on encrypted PDF document.
:pdf-allow-copy-content:: Allow content to be copy-pasted from the PDF document. (Allowed values: true, false. Default true.)
:pdf-allow-edit-content:: Allow content of the PDF document to be edited. (Allowed values: true, false. Default true.)
:pdf-allow-assemble-document:: Allow inserting, deleting, or rotating pages in the PDF document. (Allowed values: true, false. Default true.)
:pdf-allow-edit-annotations:: Allow annotations and signatures to be added to the PDF document. (Allowed values: true, false. Default true.)
:pdf-allow-print:: Allow PDF document to be printed, physically or to file. (Allowed values: true, false. Default true.)
:pdf-allow-print-hq:: Allow PDF document to be printed in high quality. (Allowed values: true, false. Default true.)
:pdf-allow-fill-in-forms:: Allow forms to be filled in the PDF document. (Allowed values: true, false. Default true.)
:pdf-allow-access-content:: Allow text and graphics extraction from the PDF document for accessibility purposes. (Allowed values: true, false. Default true.)
:pdf-encrypt-metadata:: Specify encryption of the metadata stream. (Allowed values: true, false. Default false.)