Relaton

AsciiBib -- Nested definition list syntax

Defining AsciiBib using nested lists

Purpose

This AsciiBib syntax utilizes a definition list of element name and element contents, with nested definition lists for nested structures.

If a nested definition is given for an element, the element itself has a blank definition.

Basic attributes

As with the Relaton YAML representation, if an element in Relaton XML has attributes, the content of the element is represented in YAML with a content key:

<title type="main">Geographic information</title>
title::
  type::: main
  content::: Geographic information

Element arrays

Similar to the Relaton YAML representation, repeating elements in an object can be realised as ordered or unordered lists.

language::
  . en
  . fr

EXAMPLE:

[[ISO-19115-1]]
[%bibitem]
== {blank}
docid::
  type::: ISO
  id::: 19115-1
language::
  . en
  . fr

AsciiBib also supports representing repeating elements by repeating the key for that entry. This will almost always be more straightforward to use in AsciiDoc:

language:: en
language:: fr

EXAMPLE:

[[ISO-19115-1]]
[%bibitem]
== {blank}
docid::
  type::: ISO
  id::: 19115-1
language:: en
language:: fr

Hierarchical attributes

Each Relaton entry in a bibliography is represented in Metanorma AsciiDoc through a subclause with option attribute [%bibitem]. Any title given to the subclause is treated as the title for the bibliographic entry, with language en, script Latn, format text/plain, and type main.

So the following is a very simple reference in Metanorma AsciiDoc:

[%bibitem]
== {blank}
id:: iso19115-3
docid::
  type::: ISO
  id::: 19115-3
docid::
  type::: ISO
  id::: TC211
type:: standard

Empty title

A title in the heading will be automatically treated as the English title with type main.

In the case where the bibliographic item is non-English, or not a main title (e.g. it only has an abbreviated or subtitle), you should encode the title using attributes.

Here, the subclause title should be left as , and the desired title should be given in the content body:

[%bibitem]
== {blank}
id:: iso19115-3
title::
  language::: fr
  script::: Latn
  format::: text/plain
  type::: main
  content::: Information géographique

Note the use of content as a key to represent the contents under the title tag.

Anchors

The anchor crossreference for the bibliographic entry may be encoded as either the id entry in the definition list, or as the normal AsciiDoc anchor on the subclause, which takes priority:

[[ISO-19115-3]]
[%bibitem]
== {blank}
docid::
  type::: ISO
  id::: 19115-3
type:: standard

Nesting limitations and workarounds

AsciiBib relies on basic AsciiDoc syntax, and is therefore subject to its limitations.

AsciiDoc does not recognise definition lists more than four levels deep. If deeper nesting is needed, you will need to attach a new definition list with a list continuation, with the definition list depth reset back to one:

[[ISO-19115-3]]
[%bibitem]
== {blank}
docid::
  type::: ISO
  id::: 19115-3
type:: standard
contributor::
  role::: author
  person:::
    name::::
+
--
completename::
  language::: en
  content::: Fred
--

(This is very awkward, and AsciiBib path syntax provides a workaround.)

The most heavily nested parts of a Relaton entry are the contributors, series, and relations.

Each of these can be marked up as subclauses within the entry, with the clause titles contributor, series, and relation. Each subclause contains a new definition list, with its definition list reset to zero depth; the subclauses can be repeated for multiple instances of the same subentity.

Metanorma-specific information

In Metanorma, AsciiBib citations can be combined with other AsciiDoc citations in the same Metanorma document. However, AsciiDoc citations MUST precede AsciiBib citations.

Each AsciiBib citations constitutes a subclause of its own, and Metanorma will (unsuccessfully) attempt to incorporate any trailing material in the subclause, including AsciiDoc citations, into the current AsciiBib citation.

The following is Metanorma AsciiDoc markup corresponding to the YAML given in Relaton YAML representation:

[[ISO-19115-3]]
[%bibitem]
== {blank}
title::
  type::: main
  content::: Geographic information
title::
  type::: subtitle
  content::: Metadata
title::
  type::: parttitle
  content::: Part 3: XML schema implementation for fundamental concepts
type:: standard
docid::
  type::: ISO
  id::: 19115-3
edition:: 1
language:: en
script:: Latn
version::
  revision_date::: 2019-04-01
  draft::: draft
biblionote::
  type::: bibnote
  content:::
+
--
Paper format is not available for this standard. Only PDF.
--
docstatus::
  stage::: 90
  substage::: 90.92
  iteration::: iteration
date::
  type::: issued
  value::: 2016
date::
  type::: published
  from::: 2016-06
  to::: 2016-08
date::
  type::: accessed
  value::: 2015-05-20
abstract::
  content:::
+
--
ISO/TS 19115-3:2016 defines an integrated XML implementation of ISO 19115‑1, ISO 19115‑2, and concepts from ISO/TS 19139 by defining the following artefacts ...
--
copyright::
   owner:::
     name:::: International Organization for Standardization
     abbreviation:::: ISO
     url:::: www.iso.org
   from::: 2016
   to::: 2020
link::
  type::: src
  content::: https://www.iso.org/standard/32579.html
link::
  type::: obp
  content::: https://www.iso.org/obp/ui/#iso:std:iso:ts:19115:-3:ed-1:v1:en


=== Contributor

organization::
  name::: International Organization for Standardization
  url::: www.iso.org
  abbreviation::: ISO
role::
  type::: publisher
  description::: Publisher role

=== Contributor
person::
  name:::
    completename::::
+
--
content:: A. Bierman
language:: en
--
  affiliation:::
    organization::::
+
--
name:: ISO
abbreviation:: ISO
identifier::
type::: uri
id::: www.iso.org
--
    description:::: Affiliation description
  contact:::
    street::::
      8 Street St
    city:::: City
    postcode:::: 123456
    country:::: Country
    state:::: State
  contact:::
    type:::: phone
    value:::: +1 800-000-0000
role:: author

=== Contributor
organization::
  name::: IETF
  abbreviation::: IETF
  identifier:::
    type:::: uri
    id:::: www.ietf.org
role:: publisher

=== Contributor
person::
  name:::
    language:::: en
    initial:::: A.
    surname:::: Bierman
  affiliation:::
+
--
organization::
  name::: IETF
  abbreviation::: IETF
description::
  content::: Affiliation description
  language::: en
  script::: Latn
--
  identifier:::
    type:::: uri
    id:::: www.person.com
role:: author

=== Relation
type:: updates
bibitem::
  formattedref::: ISO 19115:2003
  bib_locality:::
    type:::: page
    reference_from:::: 7
    reference_to:::: 10

=== Relation
type:: updates
bibitem::
  type::: standard
  formattedref::: ISO 19115:2003/Cor 1:2006

=== Series
type:: main
title::
  type::: original
  content::: ISO/IEC FDIS 10118-3
  language::: en
  script::: Latn
  format::: text/plain
place:: Serie's place
organization:: Serie's organization
abbreviation::
  content::: ABVR
  language::: en
  script::: Latn
from:: 2009-02-01
to:: 2010-12-20
number:: serie1234
partnumber:: part5678

=== Series
type:: alt
formattedref::
  content::: serieref
  language::: en
  script::: Latn