Metanorma: Aequitate Verum

Learning Metanorma

References

References are an integral part of standards. The main mechanism for references are anchors and destinations. There are four types of references:

  • Hyperlinks to an external source, for example a link to a website

  • Metadata references

  • Internal references to a section, image, table, etc.

  • Bibliographic entries

AsciiDoc lets you include links to external sources, and sources to files within the same project.

To reference an internal source:

  1. Use the link macro to include a link to a file. The syntax looks like this: link:PATH[].

  2. Add link text in square brackets after the path.

    Example of an internal link
    Download the latest link:downloads/report.pdf[Report]!

To reference an external source:

  1. Paste the URL into the document.

  2. Add link text in square brackets after the URL (optional) URL[Link text].

    Example of an external link
    http://www.iso.org/[International Organization for Standardization].

Metadata references

Every document contains a set of metadata to describe the document. You can insert a metadata reference by putting the attribute in curly braces {attribute}. The reference will be replaced with the value in the rendered output.

:technical-committee-number: 2
:technical-committee: Fasteners
:subcommittee-number: 11
:subcommittee: Fasteners with metric external thread

This document was prepared by Technical Committee ISO/TC {technical-committee-number}, _{technical-committee}_, Subcommittee SC {subcommittee-number}, _{subcommittee}_.

Internal references

To link to an important section, table, figure, formula, or list item in your document:

  1. Set an anchor using double square brackets before the content you want to reference: [[anchor]].

    Example for an anchor preceding an image
    [[figureC-1]]
.Typical gelatinization curve
image::images/rice_image2.png[Image of the gelatinization curve]
    references img anchor
    Figure 1. Rendered image caption

  2. To reference an anchor, type the anchor name like this <<anchor>>.

     <<figureC-1>> gives an example of a typical gelatinization curve.
    references img target
    Figure 2. Rendered reference

  3. To set an alternative text other than the anchor text, append the text inside the brackets using a comma.

     <<figureC-1, The diagram>> gives an example of a typical gelatinization curve.

Auto-numbering of references

Metanorma automatically numbers and names references; because they are autonumbered, they will be renumbered automatically if you insert any new text of the same type.

Since the markup will be converted into XML, the anchor must follow the XML namespace conventions. Therefore, an anchor name name must not contain:

  • colons

  • whitespaces

  • words starting with numbers

If you want to learn more about the technical aspects of cross-references, read Deep-dive into cross-references.

Bibliographic entries

Most standard documents contain two sections with bibliographic references, namely the “normative references” and the “bibliography” (informative references). Every bibliographic section must be preceded by the style attribute [bibliography] so that bibliographic references are recognized as such.

Entering a bibliographic entry

To enter a reference entry:

  1. Start a new unordered list (*) item.

  2. Enter triple square brackets ([[[]]]) which contain:

    • The anchor name used to reference this entry

    • A document identifier

    Syntax for a bibliographic entry
    * [[[anchor,document identifier or reference tag]]], _reference list text_

  3. After the triple brackets, you may include the reference text in italics, for example the title of the document.

    Note
    		 Metanorma uses Relaton to automatically fetch resource descriptions from the SDO’s web site. If Metanorma recognizes a document identifier, it will overwrite any title you provide with the authoritative title of the reference.

Referencing a bibliographic entry

To cite an entry from your bibliography:app-name:

  1. Enter the anchor name like this: <<ISO20483>>.

  2. To specify a location within the cited document, you can add localities in the brackets like so: <<ISO20483, part=IV,chapter=3,paragraph=12>>.

Bibliography example

The following code sample illustrates how a bibliography section looks like in AsciiDoc Metanorma.

Example for a bibliography section
[bibliography]
== Normative references

* [[[ISO20483,ISO 20483:2013]]], _Cereals and cereal products -- Determination of moisture content -- Reference method_
* [[[ISO6540,ISO 6540:1980]]]. _Maize -- Determination of moisture content (on milled grains and on whole grains)_

Gets rendered as:

  • ISO 20483:2013. Cereals and cereal products — Determination of moisture content — Reference method

  • ISO 6540:1980. Maize — Determination of moisture content (on milled grains and on whole grains)

Practice time

The code for this exercise is available on GitHub.

The corresponding file is named exercise-2-4-3.adoc

Let’s add some references to the sample document.

Internal references:

  • Create an anchor for the table called tab-properties-of-the-descriptiontype-structure

  • Replace the word "ANCHOR" in line 44 with a reference to the table.

Bibliographic references: The text references some standards which don’t have a matching entry in the bibliography section. Add the following bibliographic references:

Hint

Setting an anchor: [[anchor]]

Referencing an anchor: <<anchor>>

Let’s summarize what we’ve learnt so far.

Start next lesson »