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