Metanorma plugin that allows you to access data from the glossarist dataset inside a Metanorma document.
Add this line to your application's Gemfile:
gem 'metanorma-plugin-glossarist'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install metanorma-plugin-glossarist
In order to use the macros in Metanorma, add the gem gem metanorma-plugin-glossarist
in your Gemfile.
Currently, there are 6 macros available for this plugin and all of them support all Liquid syntax expressions, including:
:glossarist-dataset: <dataset name>:<dataset path>
[glossarist,<dataset path>, [filters], <dataset name>]
glossarist::render[<dataset name>, <term>]
glossarist::import[<dataset name>]
glossarist::render_bibliography_entry[<dataset name>, <term>]
glossarist::render_bibliography[<dataset name>]
There are 2 ways of loading a dataset
:glossarist-dataset: <dataset name>:<dataset path>
[glossarist,<dataset path>, [filters], <dataset name>]
:glossarist-dataset: <dataset name>:<dataset path>
This will load the glossarist data from <dataset path>
into <dataset name>
which can be used anywhere in the document after this line.
Suppose we have a term named foobar
in our dataset with the definition The term foobar is used as metasyntactic variables and placeholder names in computer programming
:glossarist-dataset: dataset:./path/to/glossarist-dataset
=== Section 1
{{ dataset['foobar']['eng'].definition[0].content }}
this will output
=== Section 1
The term foobar is used as metasyntactic variables and placeholder names in computer programming
[glossarist,<dataset path>, [filters], <dataset name>]
This will load the glossarist data from <dataset path>
into <dataset name>
which can be used in the given block. Filters are optional and can be used to filter and/or sort the loaded concepts from the glossarist dataset multiple filters can be added by separating them with a semicolon ;
. Filter can be added by adding filter='<filters to apply>;<another filter>'
Available filters are:
sort_by:<field name>
: will sort the dataset in ascending order of the given field values e.g sort_by:term
will sort concepts in ascending order based on the term.<field name>:<values>
: will only load a concept if the value of the given field name is equal to the given value e.g group=foo
will only load a concept if it has a group named foo
or lang=ara
will only load Arabic translations for all concepts.Suppose we have the following terms in our dataset
Name | Definition | Groups |
---|---|---|
foo | The term foo is used as metasyntactic variables and placeholder names in computer programming | foo |
bar | The term bar is used as metasyntactic variables and placeholder names in computer programming | foo, bar |
baz | The term baz is used as metasyntactic variables and placeholder names in computer programming | baz |
=== Definitions
[glossarist, /path/to/glossarist-dataset, dataset]
----
{%- for concept in dataset -%}
==== {{ concept.term }}
{{ concept.eng.definition[0].content }}
{%- endfor -%}
----
this will output
=== Section 1
==== foo
The term foo is used as metasyntactic variables and placeholder names in computer programming
==== bar
The term bar is used as metasyntactic variables and placeholder names in computer programming
==== baz
The term baz is used as metasyntactic variables and placeholder names in computer programming
Applying sorting and filtering by group
=== Definitions
[glossarist, /path/to/glossarist-dataset, filter='group=foo;sort_by=term', dataset]
----
{%- for concept in dataset -%}
==== {{ concept.term }}
{{ concept.eng.definition[0].content }}
{%- endfor -%}
----
this will output
=== Section 1
==== bar
The term bar is used as metasyntactic variables and placeholder names in computer programming
==== foo
The term foo is used as metasyntactic variables and placeholder names in computer programming
The full concept model (a concept can have multiple localized concepts) is available through the block as follows:
{
# UUIDs for localized concept mappings
"localized_concepts" => {
"eng" => "<uuid>", # English concept UUID
"fre" => "<uuid>" # French concept UUID
},
# Main concept term
"term" => "<string>",
# Language-specific content (structure repeated for each language code)
"<language_code>" => {
"dates" => [], # Array of relevant dates
"definition" => [ # Array of definition objects
{
"content" => "<string>" # Definition text
}
],
"examples" => [], # Array of example objects
"id" => "<string>", # Concept ID
"notes" => [ # Array of note objects
{
"content" => "<string>" # Note text
}
],
"sources" => [ # Array of source objects
{
"origin" => {
"ref" => "<string>" # Reference citation
},
"type" => "<string>", # Source type (e.g. "lineage")
"status" => "<string>" # Status (e.g. "identical")
}
],
"terms" => [ # Array of term objects
{
"type" => "<string>", # Term type (e.g. "expression")
"normative_status" => "<string>", # Status (e.g. "preferred")
"designation" => "<string>", # Term text
"grammar_info" => [ # Array of grammar objects
{
"preposition" => boolean,
"participle" => boolean,
"adj" => boolean,
"verb" => boolean,
"adverb" => boolean,
"noun" => boolean,
"gender" => ["<string>"], # Array of grammatical genders
"number" => ["<string>"] # Array of grammatical numbers
}
]
}
],
"language_code" => "<string>" # ISO language code
}
}
The language codes used are ISO 639-* 3-character codes, as described in the Glossarist Concept model.
An example of the full model (from ISO/IEC 2382:2015):
{
"localized_concepts" => {
"eng" => "01134f51-b88c-5214-8909-5d271ea619cf",
"fre" => "f290a3af-f1b3-527a-9045-a2dfcc0caf5a"
},
"term" => "concept description",
"eng" => {
"dates" => [],
"definition" => [
{
"content" => "data structure describing the class of all known instances of a concept"
}
],
"examples" => [],
"id" => "2122978",
"notes" => [
{
"content" => "concept description: term and definition standardized by ISO/IEC [ISO/IEC 2382-31:1997]."
},
{
"content" => "31.02.02 (2382)"
}
],
"sources" => [
{
"origin" => {
"ref" => "ISO/IEC 2382-31:1997"
},
"type" => "lineage",
"status" => "identical"
},
{
"origin" => {
"ref" => "Ranger, Natalie * 2006 * Bureau de la traduction / Translation Bureau * Services linguistiques / Linguistic Services * Bur. dir. Centre de traduction et de terminologie / Dir's Office Translation and Terminology Centre * Div. Citoyenneté et Protection civile / Citizen. & Emergency preparedness Div. * Normalisation terminologique / Terminology Standardization"
},
"type" => "lineage",
"status" => "identical"
}
],
"terms" => [
{
"type" => "expression",
"normative_status" => "preferred",
"designation" => "concept description",
"grammar_info" => [
{
"preposition" => false,
"participle" => false,
"adj" => false,
"verb" => false,
"adverb" => false,
"noun" => false,
"gender" => [],
"number" => ["singular"]
}
]
}
],
"language_code" => "eng"
},
"fre" => {
"dates" => [],
"definition" => [
{
"content" => "structure de données qui décrit la classe des instances connues d'un concept"
}
],
"examples" => [],
"id" => "2122978",
"notes" => [
{
"content" => "description de concept : terme et définition normalisés par l'ISO/CEI [ISO/IEC 2382-31:1997]."
},
{
"content" => "31.02.02 (2382)"
}
],
"sources" => [
{
"origin" => {
"ref" => "ISO/IEC 2382-31:1997"
},
"type" => "lineage",
"status" => "identical"
},
{
"origin" => {
"ref" => "Ranger, Natalie * 2006 * Bureau de la traduction / Translation Bureau * Services linguistiques / Linguistic Services * Bur. dir. Centre de traduction et de terminologie / Dir's Office Translation and Terminology Centre * Div. Citoyenneté et Protection civile / Citizen. & Emergency preparedness Div. * Normalisation terminologique / Terminology Standardization"
},
"type" => "lineage",
"status" => "identical"
}
],
"terms" => [
{
"type" => "expression",
"normative_status" => "preferred",
"designation" => "description de concept",
"grammar_info" => [
{
"preposition" => false,
"participle" => false,
"adj" => false,
"verb" => false,
"adverb" => false,
"noun" => false,
"gender" => ["f"],
"number" => ["singular"]
}
]
}
],
"language_code" => "fre"
}
}
This can be used to render a single concept from the loaded dataset. See Loading Dataset to load a dataset. This will use the default template for rendering concepts
glossarist::render[<dataset name>, <term>]
Suppose we have a term named foobar
in our dataset with the definition The term foobar is used as metasyntactic variables and placeholder names in computer programming
:glossarist-dataset: dataset:./path/to/glossarist-dataset
=== Section
glossarist::render[dataset, foobar]
then the output will be
=== Section
==== entity
concrete or abstract thing that exists, did exist, or can possibly exist, including associations among these things
This will render all the concepts from the loaded dataset using default template for rendering concepts
glossarist::import[<dataset name>]
This will render a bibliography for a single term in the loaded dataset using the default template for bibliography
glossarist::render_bibliography_entry[<dataset name>, <term>]
Suppose we have a concept foo
with the ref ISO/TS 14812:2022
, then we can render the bibliography for this like
:glossarist-dataset: dataset:./path/to/glossarist-dataset
glossarist::render_bibliography_entry[dataset, foo]
then the output will be
* [[[ISO_TS_14812_2022,ISO/TS 14812:2022]]]
This will render all the bibliographies for the given dataset
glossarist::render_bibliography[<dataset name>]
Suppose we have following concepts in dataset
foo
with ref ISO/TS 14812:2022
bar
with ref ISO/TS 14812:2023
then we can render the bibliography for this like
:glossarist-dataset: dataset:./path/to/glossarist-dataset
glossarist::render_bibliography[dataset]
then the output will be
* [[[ISO_TS_14812_2022,ISO/TS 14812:2022]]]
* [[[ISO_TS_14812_2023,ISO/TS 14812:2023]]]
==== {{ concept.term }}
<type>:[designation for the type]
{{ dataset[<concept name>]['eng'].definition[0].content }}
{% for example in <dataset name>[<concept name>]['eng'].examples %}
[example]
{{ example.content }}
{% endfor %}
{% for note in <dataset name>[<concept name>]['eng'].notes %}
[NOTE]
====
{{ note.content }}
====
{% endfor %}
{% for source in <dataset name>[<concept name>]['eng'].sources %}
[.source]
<<{{ source.origin.ref | replace: ' ', '_' | replace: '/', '_' | replace: ':', '_' }},{{ source.origin.clause }}>>
{% endfor %}
==== foobar
admitted:[E]
The term foobar is used as metasyntactic variables and placeholder names in computer programming
[example]
example for the term
[NOTE]
====
note for the term
====
[.source]
<<ISO_TS_14812_2022,foo_bar_id>>
* [[[{{ source.origin.ref | replace: ' ', '_' | replace: '/', '_' | replace: ':', '_' }},{{ source.origin.clause }},{{source.origin.ref}}]]]
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/metanorma-plugin-glossarist. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
The gem is available as open source under the terms of the 2-Clause BSD License.
Everyone interacting in the Metanorma::Plugin::Glossarist project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.