Termbase entry reference: linking a term to an internal/external term ID

[ronaldtse]

This syntax proposal aims to solve two problems.

1. Within "Terms and definitions", it is often necessary to refer and link to another term that is either defined within this clause or in a separate standard.

a. Referring to within this clause.

e.g.

== Terms and definitions

=== call number

reference provided to enable the custodian to locate a _document_ (<<term_document>>) within a repository

b. Referring to a term in another clause.

e.g.

== Content

<<part-11>> provides guidelines that are recommended for the development of terminology for _concepts_ (<<ISO_22745-2,clause 4.1>>) for cataloguing.

2. Linking to external termbases. A term can be sourced directly from an external termbase, and within the content we can also refer to an external term.

a. Referring to a supported termbase.

e.g.

== Terms and definitions
=== special concept
[.source]
<<termbase:IEV 135-60-11>>
# Maybe we can fetch from OBP too??

=== another special concept
[.source]
<<termbase:Geolexica 1234>>

a. Referring words to another termbase

e.g.

== Content

This content is about a <<termbase:IEV 1234,special concept>>.

[opoudjis]

(((electron,IEV:135-13-13)))
(((electricity,IEV:"Electricity")))

(((electrode,urn:...iso:12345:ed-1:terms:3.2)))

(((geodetic,Geolexica(id: 123))))

Something like this

[ronaldtse]

Implement in this order:

1. Link a local term within the document.

== Terms and definitions

[[term-electron]]
=== electron
blah
...

These (((electrons, term-electron))) swirl around.

2. Link an external term in a separate document

[bibliography]
== Normative references
* [[[blah, blah]]], foo bar

== clause

These (((electrons, blah, clause=3.1))) swirl around.

We will need to consider how to link a term from an external MN XML document.

3. Link an external term in a remote termbase. These remote termbases need to be supported (i.e. implemented) in MN.

[bibliography]
== Normative references

=== electron
[termbase-import]
IEV:135-13-13

== clause

These (((electrons, IEV:135-13-13))) swirl around.

[opoudjis]

This means a new Metanorma element, which links to a termbase (or to a term within the current document, or to an external document), and which is rendered like a normal word—but with a definition accompanying it in markup.

[opoudjis]

This shall be concept. The attributes of concepts are:

• term (the label of the concept in a formal vocabulary)
• source (the formal vocabulary; may be a document reference, or the current document—reserved word "this", or a termbase label that is recognised)
• id (the identifier of the term within the source; can be a locality for a document reference, an anchor for the current document, a URL, or a key)

We have three different interpretations of source and id depending on the class of source, which will be a nightmare to process. Better to break the attributes up by class of source. So:

• term
• sourcetype: "this", "citation", "termbase"
• bibitemid: = source for sourcetype = "citation", else ignored
• termbase: = source for sourcetype = "termbase", else ignored
• target: = id for sourcetype = "this", else ignored
• locality: = id for sourcetype = "citation", else ignored
• target: = id for sourcetype = "termbase"

We can further compact the representation by using eref within the concept for sourcetype = citation, xref for sourcetype = this, and a new termbaseref for sourcetype = termbase. And have the three be mutually exclusive. So:

<concept term="electron"><xref target="term-electron">electrons</xref></concept>

<concept term="electron"><eref type="inline" bibitemid="blah" citeas="ISO 216"><locality type="clause">3.1</locality>electrons</eref></concept>

<concept term="electron"><termref termbase="IEV" target="135-13-13">electrons</termref></concept>

These will be marked up as a "concept" macro, parameterised in case of termbases:

concept:[term-electron,electrons,term]
concept:[blah,clause=3.1,electrons,term]
concept:IEV[135-13-13,electrons,term]

As is currently already being done with cross-references vs citations, Standoc will determine whether the macro is referring to the current document or an external document, based on whether the id is listed among the references of the document.

The distinct term attribute is optional. The macro recognises localities, and keeps them with the "word" term, so that they can be processed just as erefs are.

[opoudjis]

Uh oh. Can't have a macro that optionally takes a target: concept:[X,Y] and concept:T[X,Y] are mutually exclusive. But I've cleverly overruled the built in behaviour of Asciidoctor, because the alternative is just too messy.

It would be nice if the Asciidoctor Macro DSL was documented...

[ronaldtse]

How about just:

concept:[<<term-electron>>,electrons,term]
concept:[<<blah,clause=3.1>>,electrons,term]
concept:[IEV:135-13-13,electrons,term]

?

[opoudjis]

Agreed to change to (or attempt it):

{{term-electron,electron[,electrons]}} (the canonical term is by default the text)
{{blah,clause=3.1,electron[,electrons]}}
{{IEV:135-13-13,electron[,electrons]}}}

For rendering, if neither term nor text is supplied, render as "[Term defined in (citation)]".