relaton-render 0.4.2 → 3.0.0.pre.alpha.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c21e6af4c8c19084d12c883fcc12ec4828965563d84eefa9ad3776fbd4997bf6
-  data.tar.gz: df7f7dbbc98ac5de46e904cc572d9ed131921ec7b6418e3080e5115a69ab0647
+  metadata.gz: e2d52f05f42c17071799e1cc19e71d0b84f84a0550430d287e4d8cf4dee389a6
+  data.tar.gz: 4170319d650b7d3de48553d5fcddb15857b24939e9a6e008d7f74c095f849f60
 SHA512:
-  metadata.gz: 2d0a91b6196e46b51e2aa88dd923608b885ecc369e63e56bc16fd90d5458f3300c8017d73f0524ecb32b7d811d391be0da4778649559df8a0f540b85150baf4e
-  data.tar.gz: aa14c96d47a1b354c26dd4b99df07c334dd9404f8faf04bd7686d3071b85cc0d0769a81976d8ae83846d5334a4c36fa02a3ef0e5d66f152a80dc6ba66d5b960f
+  metadata.gz: 021e4859ac3ba1f2dda762db881d1322677578359dc0f9a7c319435d7692a36fb6dcc1b96b9b068ca3ed65f9a621648da698962e49d2d2b132adbf5ea2ee66ff
+  data.tar.gz: ad7e119b111cac93e1c70fd0af76431a33dc9e95a5508ca866ab556c7b7e3484e7ae31c1981778f2a86ad6c35ba5ecfdfee9799b2a8c1e21480184f81915bc98

data/.github/workflows/rake.yml

@@ -8,6 +8,11 @@ on:
     tags: [ v* ]
   pull_request:
 
+permissions:
+  contents: write
+
 jobs:
   rake:
-    uses: relaton/support/.github/workflows/rake.yml@master
+    uses: metanorma/ci/.github/workflows/generic-rake.yml@main
+    secrets:
+      pat_token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}

data/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+# Auto-generated by Cimas: Do not edit it manually!
+# See https://github.com/metanorma/cimas
+name: release
+
+on:
+  workflow_dispatch:
+    inputs:
+      next_version:
+        description: |
+          Next release version. Possible values: x.y.z, major, minor, patch (or pre|rc|etc).
+          Also, you can pass 'skip' to skip 'git tag' and do 'gem push' for the current version
+        required: true
+        default: 'skip'
+  repository_dispatch:
+    types: [ do-release ]
+
+jobs:
+  release:
+    uses: relaton/support/.github/workflows/release.yml@main
+    with:
+      next_version: ${{ github.event.inputs.next_version }}
+    secrets:
+      rubygems-api-key: ${{ secrets.RELATON_CI_RUBYGEMS_API_KEY }}
+

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+Gemfile.lock
+.vscode/
+bin/rspec

data/.rubocop.yml

@@ -1,10 +1,10 @@
 # Auto-generated by Cimas: Do not edit it manually!
 # See https://github.com/metanorma/cimas
 inherit_from:
-  - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/main/ci/rubocop.yml
 
 # local repo-specific modifications
 # ...
 
 AllCops:
-  TargetRubyVersion: 2.5
+  TargetRubyVersion: 3.4

data/Gemfile

@@ -3,6 +3,22 @@ Encoding.default_internal = Encoding::UTF_8
 
 source "https://rubygems.org"
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 gemspec
+
+group :development, :test do
+  gem "canon"
+  gem "relaton", ">= 3.0.0.pre.alpha", "< 4" # the model fixtures; the engine itself is model-agnostic
+  gem "debug"
+  gem "iso-690-test-suite", github: "relaton/iso-690-test-suite"
+  gem "rake", ">= 12.3.3"
+  gem "rspec", "~> 3.0"
+  gem "simplecov"
+end
+
+begin
+  eval_gemfile("Gemfile.devel")
+rescue StandardError
+  nil
+end

data/README.adoc

@@ -2,7 +2,7 @@
 
 image:https://img.shields.io/gem/v/relaton-render.svg["Gem Version", link="https://rubygems.org/gems/relaton-render"]
 image:https://github.com/metanorma/relaton-render/workflows/rake/badge.svg["Build Status", link="https://github.com/metanorma/relaton-render/actions?workflow=rake"]
-image:https://codeclimate.com/github/metanorma/relaton-render/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/metanorma/relaton-render"]
+// image:https://codeclimate.com/github/metanorma/relaton-render/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/metanorma/relaton-render"]
 
 Gem that takes a https://github.com/relaton/relaton[Relaton] bibliographic description and 
 a configuration, and generates a https://www.metanorma.org[Metanorma] XML rendering of that description.
@@ -35,9 +35,9 @@ The gem processes either Relaton XML, or native Relaton classes.
 The gem is intended to be inherited from by Metanorma flavours, which may specialise it with their own
 code. The templates are however intended to determine much of the rendering.
 
-Gems can provide their configurations in YAML files, and parse them before passing them to the call to Iso690Render.
-The built-in values for Iso690Render are given in `/lib/iso690render/config.yml`, and can be overridden by
-the parameters of initialising Iso690Render.
+Gems can provide their configurations in YAML files, and parse them before passing them to the call to Relaton::Render.
+The built-in values for Relaton::Render are given in `/lib/relaton/render/general/config.yml`, and can be overridden by
+the parameters of initialising Relaton::Render.
 
 The parameters are:
 
@@ -70,7 +70,8 @@ author and date. It should not be used for rendering of references aligned to th
 Given a collection of Relaton bibitem objects (or equivalent Relaton XML, wrapped in `<references>`), 
 `render_all(bibliography, type: type)`
 will output a hash of objects, with information to be used both for rendering references, and for generating citations.
-This method addresses the disambiguation of citiations, and changes to rendering of references reflecting that disambiguation.
+This method addresses the disambiguation of citations, and changes to rendering of references reflecting that disambiguation
+(e.g. differentiating two works with the same wuthor surname and year: _Jones 1996a_ and _Jones 1996b_).
 For that reason, this method should be used for references using the author-date citation system.
 
 The `type` argument of `render_all` reflects the citation system to be used. 
@@ -90,261 +91,15 @@ if called with `type: "author-date"`.
 The author and date are differentiated so that consumers can separate them in citations -- e.g. "Jones (1996) claims", 
 "(Jones 1996, 1997)".
 
-== Configuration
-
-=== Templates
-
-There is one template provided for each of the bibliographic types recognised by Relaton (`/bibitem/@type`), and a default template:
-
-Currently supported:
-
-* article 
-* book 
-* booklet 
-* manual 
-* proceedings 
-* presentation 
-* thesis 
-* techreport 
-* standard 
-* unpublished 
-* electronic resource 
-* inbook 
-* incollection 
-* inproceedings 
-* journal 
-* website
-* webresource
-* dataset
-
-Not currently supported:
-
-* map 
-* audiovisual 
-* film 
-* video 
-* broadcast 
-* software 
-* graphic_work 
-* music 
-* performance 
-* patent 
-* archival 
-* social_media 
-* alert 
-* message 
-* conversation 
-* misc (default)
-
-
-In Metanorma, not all types are used, but there are exemplars for all of these given on this site, following
-the human-readable style used in ISO 690. These can be overridden by supplying corresponding paramerers in the call
-to initialise Iso690Render.
-
-Each `template` is a string marked up with https://shopify.github.io/liquid/[Liquid Markup], with the following fields
-drawn from the bibliographic item:
-
-|===
-| Field   | Relaton XPath | Multiple | Can come from host | Note
-
-| title   | ./title | | |
-| edition | ./edition | | Y | If numeric value, is given internationalised rendering of "nth edition", as set in edition_numbering. Otherwise, the textual content of the tag is given.
-| edition_raw | ./edition | | Y | The strict textual content of the tag is given.
-| edition_num | ./edition[@number] | | Y | 
-| medium  | ./medium | | Y |
-| place   | ./place | | Y |
-| publisher | ./contributor[role/@type = 'publisher']/organization/name | | Y | 
-| distributor | ./contributor[role/@type = 'distributor']/organization/name | | Y | 
-| standardidentifier | ./docidentifier[not(@type = 'metanorma' or @type = 'ordinal')] | Y | |
-| status | ./status | | | Rendering varies by flavour
-| uri | ./uri[@type = 'doi' or @type = 'uri' or @type = 'src' or true] | | |
-| access_location | ./accessLocation | | Y |
-| extent | ./extent | Y | | Render with standard abbreviations for pp, vols, with n-dash, with delimiting of multiple locations
-| creatornames | ./contributor[role/@type = 'author'] \| ./contributor[role/@type = 'performer'] \| ./contributor[role/@type = 'adapter'] \| ./contributor[role/@type = 'translator'] \| ./contributor[role/@type = 'editor'] \| ./contributor[role/@type = 'publisher'] \| ./contributor[role/@type = 'distributor'] \| ./contributor | Y | | <<nametemplate,`nametemplate`>> applied to each name; joining template from internationalisation applied to multiple names
-| authorcite | ./contributor[role/@type = 'author'] \| ./contributor[role/@type = 'performer'] \| ./contributor[role/@type = 'adapter'] \| ./contributor[role/@type = 'translator'] \| ./contributor[role/@type = 'editor'] \| ./contributor[role/@type = 'publisher'] \| ./contributor[role/@type = 'distributor'] \| ./contributor | Y | | <<authorcitetemplate,`authorcitetemplate`>> applied to each name; joining template from internationalisation applied to multiple names
-| role | ./contributor[role/description] \| ./contributor[role/@type] | | | 
-| date | ./date[@type = 'issued'] \| ./date[@type = 'circulated'] \| ./date | | Y |
-| date_updated | ./date[@type = 'updated'] | | Y | 
-| date_accessed | ./date[@type = 'accessed'] | | Y | 
-| series | ./series[@type = 'main' or not(@type) or true] | | Y | <<seriestemplate,`seriestemplate`>> applies to series
-| host_creatornames | ./relation[@type = 'includedIn']/ bibitem/contributor[role/@type = 'author'] | |  Y | Follows options for `creatornames`
-| host_title | ./relation[@type = 'includedIn']/ bibitem/title | Y | Y | Follows options for `creatornames`
-| host_role | ./relation[@type = 'includedIn']/ bibitem/contributor[role/description] \| ./relation[@type = 'includedIn']/ bibitem/contributor[role/@type] | | Y | 
-| type | ./@type | |
-| labels | | | text to be looked up in internationalisation configuration files: "edition", "In", "At", "Vol", "Vols", "p.", "pp" 
-|===
-
-Missing dates and places of publication are rendered as "n.d." and "n.p." or the equivalent internationalisation (`no_date`, `no_place` in the internationalisation YAML files.) However, missing dates are left as nil in standards, as undated standards indicate that the citation applies to the latest version of the standard, and not that the date is unknown.
-
-Many fields are populated either by the description of the bibliographic item itself, or by the description of the item containing it (the _host_ item: `./relation[@type = 'includedIn']/bibitem`). For example, in a paper included in an edited volume, the edition will typically be given for the editor volume, rather than for the paper. Those fields are indicated by "Can come from host" in the table.
-
-The Liquid templates use the filters defined in Liquid, such as `upcase`. We have defined some custom filters:
-
-* `capitalize_first` capitalises only the first word in a string, and does not lowercase other words in the string. So "third edition" becomes "Third edition", but "3. Aufl." does not become "3. aufl."
-
-The Liquid template surrounds each field by preceding and following punctuation.
-
-* Fields are space-delimited. So `<em>{{ title }}</em> [{{medium}}]` are two separate fields.
-* If fields are not space-delimited, this is indicated by inserting `|`. So `{{ title }}|{{ medium}}` is two fields, rendered with no space separation.
-* If the field is empty, its surrounding markup is also removed. So if there is no medium, then `[{{medium}}]` is not rendered, and the brackets will be stripped.
-* Underscore is treated as space, attaching to the preceding or following field. So `,_{{ edition }}_{{ labels['edition'] }}` is treated as the one field.
-* Underscore is escaped by \. So `<span_class="std\_note">` maps to `<span class="std_note">`.
-* If punctuation is space delimited, it is inserted regardless of preceding content. So `{{ creatornames }} ({{date}}) .` will insert the full stop whether or not the date is present.
-* Space between punctuation and before punctuation is automatically removed.
-
-For example:
-
-....
-"{{ creatornames }} ({{date}}) . <em>{{ title }}</em> [{{medium}}] ,_{{ edition }}_{{ labels['edition'] }} ."
-....
-
-If a type uses another type's template, the type is mapped to the other type's name; e.g.
-
-....
-template:
-  book: ...
-  booklet:  book
-....
-
-[[nametemplate]]
-=== Name templates
-
-The `nametemplate` is a hash of Liquid templates for the formatting of contributor names in particular positions. It
-draws on the following fields drawn from the bibliographic item:
-
-|===
-| Field  | Relaton XPath | Multiple | Note
-
-| surname[0] | ./contributor[1]/person/name/surname \| ./contributor[1]/person/name/completename | | i.e. surname is the name default
-| surname[1] | ./contributor[2]/name/surname | |
-| surname[2] | ./contributor[3]/name/surname | |
-| initials[0] | ./contributor[1]/name/initial | | If not supplied, the first letter of each given name is used instead
-| initials[1] | ./contributor[2]/name/initial | |
-| given[0] | ./contributor[1]/name/forename[1] | | If not supplied, initials are used instead
-| given[1] |  ./contributor[2]/name/forename[1] | |
-| middle[0] | ./contributor[1]/name/forename[not(first())] | Y |
-| middle[1] | ./contributor[2]/name/forename[not(first())] | Y |
-| nonpersonal[0] |./contributor[1]/organization/name | Y |
-| nonpersonal[1] |./contributor[2]/organization/name | Y |
-|===
-
-There are at least three distinct `nametemplate` instances that need to be provided, one for a single contributor (`one:`), one for two contributors (`two:`), one for three or more (`more:`), and optionally one for "et al." (`etal:`). The number of contributors for which "et al." starts being used is indicated by `etal_count`.
-
-For example:
-....
-{
-  one: "{% if nonpersonal[0] %}{{ nonpersonal[0] }}{% else %}{{ surname[0] }}, {{ given[0] }} {{ middle[0] | slice : 0 }}{% endif %}",
-  two: "{% if nonpersonal[0] %}{{ nonpersonal[0] }}{% else %}{{ surname[0] }}, {{ given[0] }} {{ middle[0] | slice : 0 }}{% endif %} &amp; {% if nonpersonal[1] %}{{ nonpersonal[1] }}{% else %}{{ given[1] }} {{ middle[1] | slice : 0 }} {{ surname[1] }}{% endif %}",
-  more: "{% if nonpersonal[0] %}{{ nonpersonal[0] }}{% else %}{{ surname[0] }}, {{ given[0] }} {{ middle[0] | slice : 0 }}{% endif %}, {% if nonpersonal[1] %}{{ nonpersonal[1] }}{% else %}{{ given[1] }} {{ middle[1] | slice : 0 }} {{ surname[1] }}{% endif %} &amp; {% if nonpersonal[2] %}{{ nonpersonal[2] }}{% else %}{{ given[2] }} {{ middle[2] | slice : 0 }} {{ surname[2] }}{% endif %}",
-  etal: "{% if nonpersonal[0] %}{{ nonpersonal[0] }}{% else %}{{ surname[0] }}, {{ given[0] }} {{ middle[0] | slice : 0 }}{% endif %}, {% if nonpersonal[1] %}{{ nonpersonal[1] }}{% else %}{{ given[1] }} {{ middle[1] | slice : 0 }} {{ surname[1] }}{% endif %} <em>et al.</em>",
-  etal_count: 6
-}
-....
-
-In the case of `more`, the `(name)[1]` entries are repeated for all additional authors above 2 and before the final author.
-
-[[authorcitetemplate]]
-=== Author citation templates
+=== Parsing single reference
 
-The `authorcitetemplate` is a subclass of the name template, configured for rendering author names for author-date citations.
-That means that it typically selects only surnames for rendering.
+Given an Relaton bibitem object (or equivalent Relaton XML), `parse(input)` will output the hash of fields that is passed into the
+Liquid templates described below for rendering: it is the hash of bibliographic fields extracted by the gem.
 
-[[seriestemplate]]
-=== Series template
-
-The `seriestemplate` is a template for the rendering of series information. It draws on the following fields drawn from the bibliographic item:
-
-|===
-| Field  | Relaton XPath | Multiple | Can come from host | Note
-
-| series_title  | ./series[@type = 'main' or not(@type) or true]/name | | Y |
-| series_abbr  | ./series[@type = 'main' or not(@type) or true]/abbreviation | | Y |
-| series_num  | ./series[@type = 'main' or not(@type) or true]/number | | Y |
-| series_partnumber  | ./series[@type = 'main' or not(@type) or true]/partnumber | | Y |
-| series_run  | ./series[@type = 'main' or not(@type) or true]/run | | Y |
-|===
-
-For example: `{% if series_abbr %}{{series_abbr}}{% else %}{{series_title}}{% endif %} ,_({{series_run}}) {{series_num}}|({{series_partnumber}})`
-
-=== Journal template
-
-The `journaltemplate` is a template for the rendering of series information, when they relate to articles in a journal. The template is distinct because of longstanding practice of rendering journal information differently from monograph series information. The template draws on the same fields as the `seriestemplate`, but because the journal title is typically italicised and the numeration is not, any italicisation needs to occur within the template.
-
-For example, the recommended practice in the current edition of ISO 690 is to give explicit volume labels:
-
-`<em>{% if series_abbr %}{{series_abbr}}{% else %}{{series_title}}{% endif %}</em> {{ labels['volume'] }}_{{series_num}} {{ labels['part'] }}_{{series_partnumber}}`
-
-A common template that drops those labels is:
-
-`<em>{% if series_abbr %}{{series_abbr}}{% else %}{{series_title}}{% endif %}</em> {{series_num}}|({{series_partnumber}})`
-
-=== Extent template
-
-The extent of a bibliographic item may be expressed differently depending on the type of bibliographic item. For example, the extent of a book chapter may be expressed as _pp. 9–20_, while the extent of an article may be expressed as just _9–20_. 
-
-To capture this, a separate template is supplied under `extenttemplate` for each bibliographic item type. For those types where none is supplied, the template given for `misc` is used as the default. 
-
-The template draws on the defined types of locality of extents; the most common of these is `volume`, `issue` (within volume; "number" for journals), and `page`. Locality types are the fields used in the Liquid templates; for example:
-
-....
-{
-  article: "{{ volume_raw }}|({{ issue_raw }}) : {{ page_raw }}"
-  misc: "{{ volume }}, {{ page }}"
-}
-....
-
-The internationalisation files define a singular and a plural version of the locality types, under `labels['extent']`.
-
-* The plural label is always used if the extent is a range (with a `<from>` and `<to>`). 
-* The singular label is used if the extent is not a range (_pp. 2–4_ vs. _p. 3_).
-* The internationalisation files include a slot where the number or number range is inserted, indicated by `%`, since this varies by language. (For instance, English has `pp. %`,  whereas Chinese has `第%页`.) 
-* The number of the volume, issue/number, or page, without accompanying labels, is given in `volume_raw`, `issue_raw`, and `page_raw`.
-
-=== Size template
-
-The size of a bibliographic item is distinct from the extent: the size is how large the item is (e.g. how many pages are in the book), whereas the extent is how much of the host item the item covers (e.g. which pages of the book are in the current chapter.) They can be displayed quite differently from extent; for example, while extent pages is given in English as _pp. 9–20_ or _p. 3_, size pages is given as _3 pp._.
-
-To capture this, a separate template is supplied under `sizetemplate` for each bibliographic item type. Again, for those types where none is supplied, the template given for `misc` is used as the default.
-
-The template draws on the defined types of locality of extents; the following are currently recognised:
-
-|===
-| Field  | Relaton XPath | Note
-
-| volume  | ./medium/size[@type = 'volume'] | With internationalisation of label
-| volume_raw  | ./medium/size[@type = 'volume'] |
-| issue  | ./medium/size[@type = 'issue'] | With internationalisation of label
-| issue_raw  | ./medium/size[@type = 'issue'] |
-| page  | ./medium/size[@type = 'page'] | With internationalisation of label
-| page_raw  | ./medium/size[@type = 'page'] |
-| data  | ./medium/size[@type = 'data'] | Unit of size is included in value
-| duration  | ./medium/size[@type = 'time'] | Expressed in ISO 8601 duration
-|===
-
-
-Locality types are the fields used in the Liquid templates; for example:
-
-....
-{
-  dataset: "{{ data }}"
-  misc: "{{ volume }}, {{ page }}, {{ data }}, {{ duration }}"
-}
-....
-
-The internationalisation files define a singular and a plural version of the locality types, under `labels['size']`.
-
-* The plural label is always used if the extent is a range (with a `<from>` and `<to>`).
-* The label is singular only if the value is `1`, else it is plural (_1 p._, _2 pp._)
-* Again, the internationalisation files include a slot where the number or number range is inserted, since this varies by language. 
-* The number of volumes or pages, without accompanying labels, is given in `volume_raw` and `page_raw`.
-* Multiple spans of the same type are joined by `+`; e.g. _xlii + 76 pp._.
+== Configuration
 
-=== Other
+For the configuation YAML used in relaton-render, refer to https://relaton.org/specs/relaton-render 
 
-In addition, the configuration includes different configuration options for rendering:
+== Documentation
 
-The internationalisation file sets the following variables, which can be overridden in configuration parameters:
-`edition_number`:: has following values corresponding to the rule-based number rules defined in https://github.com/twitter/twitter-cldr-rb[Twitter CLDR]. 
-for a language. For example, English _4th_ is defined as `["OrdinalRules", "digits-ordinal"]`, because under twitter-cldr, `4th` is generated as `4.localize(:en).to_rbnf_s("OrdinalRules", "digits-ordinal")`. If missing, the raw number is given.
-`edition`:: is the localised expression for edition, with the edition number given as %. So _4th ed.` is generated with `edition` as `% ed.`.
-`date`:: date format default, taken from https://github.com/twitter/twitter-cldr-rb[Twitter CLDR]: `to_full_s`, `to_long_s`, `to_medium_s`, `to_short_s`, or one of the `to_additional_s` formats. One value is given for each of "month_year", "day_month_year", and "date_time"; e.g. `{ month_year: to_long_s, day_month_year: to_long_s, date_time: to_long_s }`.
+* link:docs/citation-style-pack.adoc[Defining a Citation Style: the pack format] — the authoritative spec for CitationStyle YAML packs: resource types, presentation patterns, model presentation templates, locale/punctuation, inheritance and conformance.