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

Hyperlinks

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

To reference an internal source:

Use the link macro to include a link to a file. The syntax looks like this: \PATH[].
Add link text in square brackets after the path.
Example of an internal linkAsciiDoc
```
Download the latest link:downloads/report.pdf[Report]!
```

To reference an external source:

Paste the URL into the document.
Add link text in square brackets after the URL (optional) URL[Link text].
Example of an external linkAsciiDoc
```
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:

Set an anchor using double square brackets before the content you want to reference: \[[anchor]].
Example for an anchor preceding an imageAsciiDoc
```
[[figureC-1]]
.Typical gelatinization curve
image::images/rice_image2.png[Image of the gelatinization curve]
```
image::/assets/author/learn/referencesimganchor.jpg[]
To reference an anchor, type the anchor name like this: anchor
```
 <<figureC-1>> gives an example of a typical gelatinization curve.
```
image::/assets/author/learn/referencesimgtarget.jpg[]
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:

Start a new unordered list (*) item.
Enter triple square brackets ([[[]]]) which contain:

Syntax for a bibliographic entryAsciiDoc

* [[[anchor,document identifier or reference tag]]], _reference list text_

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:

Enter the anchor name like this: ISO20483.
To specify a location within the cited document, you can add localities in the brackets like so: 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 sectionAsciiDoc

[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

:exercise-file: exercise-2-4-3 include::exercises.adoc[tags=intro;exercise-2-4-3]

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

+++ <div class="cta tutorial"><a class="button" href="/learn/lessons/lesson-2-5/">Start next lesson »</a></div> ++++

Edit this page on GitHub →