pubid 0.1.2 → 1.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. checksums.yaml +4 -4
  2. data/README.adoc +77 -3
  3. data/lib/pubid/version.rb +1 -1
  4. metadata +65 -79
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 690aaebd36159f29f0c30f305e45c2a44cb27f2aa03e501d3b264af0acee6bb9
4
- data.tar.gz: dc4bf083ed329452fa61a6e2080356fc5a46b88cec2d442327d79f35bcdd1745
3
+ metadata.gz: fd93e44539bfdf58b577341e38c5a802723b0058e55feca77941ac8c3ff7eb63
4
+ data.tar.gz: 961315e34b66f01bace40aa7b154c391a2d880d98a9ba563f3aeee93d1fc8d23
5
5
  SHA512:
6
- metadata.gz: 7ac9c45a40be24fe9791acea1b15bd7f8124c60d59e594d4803c2b01dffb39d8100c2efdeae73b4da4b64096300183fd4202edd34f22fb9f0166008404376726
7
- data.tar.gz: '09789ff8bff807dfe2fcee2852137b27d77b2ef8bd32aa5e2de855c24ef276ce083fe26b854afd4d4c25f68b828085c3e484d94d325220e1b75f417c5881a3a8'
6
+ metadata.gz: 3ab7e206004ae2113c0c4153644ba772e58b213f7417fb79f32abfedd155348dfbc988d16a65cca8ffecc45f80da8b7b517fcc25e29415e4f651226875e4b58e
7
+ data.tar.gz: d45a4e3994cd2b2d84895b5bcddb9fed669eda9e4463243c164a86cb20077ce9e0ce846f6dd9751eacb0cc16fdb8240c63bee7a1eb8dbcc776b2a0b6918b7bbf
data/README.adoc CHANGED
@@ -1,8 +1,82 @@
1
- = PubID
1
+ = Publication identifiers library
2
2
 
3
3
  image:https://badge.fury.io/rb/pubid.svg["Gem Version", link="https://badge.fury.io/rb/pubid"]
4
4
 
5
- == Purpose
5
+ Pubid is a comprehensive framework for building and working with publication identifiers. It provides a robust API for creating, modifying, parsing, exporting, and verifying document identifiers, which are crucial for various document management systems and standards compliance
6
6
 
7
- This gem include all pubid-* gems for compatibility testing.
7
+ This gem includes all pubid-* gems for compatibility testing and allows parsing all identifiers from one gem.
8
8
 
9
+ == Current use cases
10
+ The current use cases, as listed below, are what we have needed until now and have discovered through use of pubid to pubid-*, metanorma-*, and relaton-* projects. Work on pubid is not complete and will be expanding during the ongoing integration process.
11
+
12
+ - building identifiers from scratch
13
+ - modifiying identifiers (e.g. basing an amendment identifier on a base identifier)
14
+ - parsing string identifiers
15
+ - exporting/importing to different formats or styles (hash, yaml, URN, etc.)
16
+ - verification of compliance for the identifier's representation standard (NIST PubID 1.0 for NIST, RFC 5141 for ISO URN), or using commonly found patterns
17
+ - verifying that a provided identifier is correct
18
+ - comparing two provided identifiers (with the option to exclude specified attributes)
19
+ - converting legacy identifiers to updated format
20
+
21
+ == Purpose and Usage Guidelines
22
+
23
+ The pubid library is intended to be used wherever operations on publication identifiers are required. It acts as an intermediary between users and publication identifiers, streamlining the processes of creation, modification, comparison, and attribute access. By centralizing these operations in pubid-core, we ensure that any updates to identifier standards are seamlessly integrated across all related projects in an ecosystem.
24
+
25
+ It is crucial to use the pubid library for all operations with identifiers to ensure that updates in identifier standards are consistently reflected in these operations, and are driven by a data representation of the identifier, rather than the identifier string. For example, if an identifier like `ISO/R 657/IV` is updated to `ISO/R 657-4:1969` by a standards body, and pubid acts on that update, the library will automatically recognize this change. Hence, comparing:
26
+ [source,ruby]
27
+ ----
28
+ Pubid::Registry.parse("ISO/R 657/IV") == Pubid::Registry.parse("ISO/R 657-4:1969")
29
+ => true
30
+ ----
31
+ or accessing the year:
32
+ [source,ruby]
33
+ ----
34
+ Pubid::Registry.parse("ISO/R 657/IV").year
35
+ => 1969
36
+ ----
37
+ will yield the updated results.
38
+
39
+ Moreover, changes in how identifiers are compared may cause some identifiers to become equal or unequal based on the latest updates. Thus, to reflect these changes accurately, the pubid library should be used for all publication identifier operations.
40
+
41
+ === Information model
42
+
43
+ Technical documents in general, and standards specifically, are routinely identified and cited by document identifier, rather than by author, title, and/or publication date, as is routine practice for other bibliographic types. These document identifiers are usually somewhat arbitrary, containing a number identifying the current document as one in a sequence of documents.
44
+
45
+ However, technical document identifiers typically also contain representation of at least some of the bibliographic information about the document. This is why bibliographic citation of technical document (particularly in other technical documents) is often restricted to just the document identifier and the title: the identifier is felt in such communities to convey all the relevant bibliographic information needed to make sense of the standard. (The expectations on what information is needed is different from other bibliographic types within their communities: authorship for example is typically corporate, dates are assumed by default to be the latest availabe edition, and the place of publication and publisher are identiified with the organisation publishing the document.)
46
+
47
+ Pubid uses semantic representation of the bibliographic information used to generate an identifier for an organisation. That is why the format of the identifier can be updated without changing the underlying semantics it encodes. Each organisation that Pubid supports has its own semantics, but there are recurring semantic fields that Pubid uses, which drive what the identifiers look like, and which correspond to bibliographic information. (The Relaton bibliographic model equivalent is linked after each definition.)
48
+
49
+ * The `publisher` is the organisation responsible for the document. Standards-defining organisations, in particular, are identified by established acronyms, such as _ISO_, _IEC_, _NIST_, which are usually prefixed to the document identifier; that prefix takes the place of a publisher field. The choice of publisher determines the flavour of Pubid that is used. (Relaton: https://www.relaton.org/model/creator/[Creator, type: Publisher])
50
+ * Technical documents are often published by multiple organisations. Such co-publication is indicated through using the acronyms of all organisations involved in the prefix; publishers after the first are indicated as `copublisher`. For example, the prefix _ISO/IEC/IEEE_ indicates that the document is copublished by all three organisations; ISO will be treated as the primary publisher by Pubid. (Relaton: https://www.relaton.org/model/creator/[Creator, type: Publisher])
51
+ * Technical documents are almost always numbered in a sequence; that `number` is used along with the publisher to identify the document uniquely. (Relaton: https://www.relaton.org/model/series/[Series number])
52
+ * Technical documents may consist of different parts, which can be referenced individually. The `part` number for the document is used in addition to the number in that case. (Relaton: https://www.relaton.org/model/citation/[Citation, type: Part])
53
+ * In special circumstances, multiple subsequent versions of a document can appear with the same number; this applies for example to multiple drafts. These subsequent versions can be indicated as `iteration`. (Relaton: https://www.relaton.org/model/edition/[Edition: Version])
54
+ * Often there is different numbering used for different types of technical document; for example, technical reports, technical notes, and standards have different number sequences in ISO. For that reason, the document `type` may be required in addition to the number. For inclusion in an identifier the organisation will typically have a standardised abbreviation for each of the document types. (Relaton: https://www.relaton.org/model/series/[Series], though Relaton for standards organisations treats these for convenience as subtypes of document, the document https://www.relaton.org/model/bibtype/[type] being `standard`)
55
+ * In some cases, different numbering is used not for different types of document, but different defined `series`. If that is the case, the organisation will typically have a standardised abbreviation for the series as well. (Relaton: https://www.relaton.org/model/series/[Series])
56
+ * Some organisations publish standards in multiple languages. In that case, the document `language` can also be provided, to indicate a particular language version.
57
+ * Technical documents are often cited undated; in that case, the latest version of the document is usually assumed. If a specific edition of a document needs to be specified in the edition, this can be done by supplying an `edition` number, the `year` of publication, or both, depending on the organisation. (Relaton: https://www.relaton.org/model/edition/[Edition], https://www.relaton.org/model/production/#date[Date])
58
+ * Unlike other documents, technical documents are often circulated and cited in draft version before they are officially published. If this is routinely done, the organisation may provide for means to specify that a document is a `draft`, or the `stage` or `status` which the document has reached in the authoring process. If stages are used in citing documents, the organisation will typically have standard abbreviations for those stages, which will be used in the identifier. (Relaton: https://www.relaton.org/model/edition/[Edition])
59
+ * Just as documents can be bibliographically related to other documents, document identifiers can be based on other document identifiers. This is done in Pubid by specifying two Pubid identifiers, with the first treated as an attribute of the second. The first common case of derived identifiers is when one document is a supplement of another (e.g. an appendix, a corrigendum); this is encoded in Pubid by specifying a `base` Pubid identifier, as an attribute of the derived document, with its own distinct `number`, `type` (e.g. _Appendix_), and `year`. The second case is when a document published by one organisation is `adopted` for use by another organisation: this often is indicated in document identifiers simply by prefixing the adopting organisation's acronym to the original identifier (e.g. _BS ISO 639_). (Relaton: https://www.relaton.org/model/relations/#derived-relations[Relations: `updates`, `adoptedFrom`])
60
+
61
+ === Usage
62
+
63
+ `Pubid::Registry#parse` resolves the pubid class related to the identifier (`Pubid::Iso::Identifier` for "ISO" identifiers) and returns an object with the parsed identifier
64
+
65
+ [source,ruby]
66
+ ----
67
+ require "pubid"
68
+
69
+ pubid = Pubid::Registry.parse("ISO/IEC 13213")
70
+ pubid.class
71
+ => Pubid::Iso::Identifier::Base
72
+ pubid.publisher
73
+ => "ISO"
74
+ pubid.copublisher
75
+ => "IEC"
76
+ pubid.number
77
+ => 13213
78
+ pubid.to_s
79
+ => "ISO/IEC 13213"
80
+ ----
81
+
82
+ You can find usage examples in the https://github.com/metanorma/pubid-core[pubid-core] repository. For more specific usage guides, refer to repositories related to specific identifier providers, such as https://github.com/metanorma/pubid-iso[pubid-iso] for ISO identifiers and https://github.com/metanorma/pubid-ccsds[pubid-ccsds] for CCSDS identifier)
data/lib/pubid/version.rb CHANGED
@@ -1,3 +1,3 @@
1
1
  module Pubid
2
- VERSION = "0.1.2".freeze
2
+ VERSION = "1.15.0".freeze
3
3
  end
metadata CHANGED
@@ -1,197 +1,183 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: pubid
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.2
4
+ version: 1.15.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Ribose Inc.
8
- autorequire:
8
+ autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2024-05-06 00:00:00.000000000 Z
11
+ date: 2025-06-04 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
- name: rake
15
- requirement: !ruby/object:Gem::Requirement
16
- requirements:
17
- - - "~>"
18
- - !ruby/object:Gem::Version
19
- version: '13.0'
20
- type: :development
21
- prerelease: false
22
- version_requirements: !ruby/object:Gem::Requirement
23
- requirements:
24
- - - "~>"
25
- - !ruby/object:Gem::Version
26
- version: '13.0'
27
- - !ruby/object:Gem::Dependency
28
- name: rspec
14
+ name: pubid-bsi
29
15
  requirement: !ruby/object:Gem::Requirement
30
16
  requirements:
31
- - - "~>"
17
+ - - '='
32
18
  - !ruby/object:Gem::Version
33
- version: '3.0'
34
- type: :development
19
+ version: 1.15.0
20
+ type: :runtime
35
21
  prerelease: false
36
22
  version_requirements: !ruby/object:Gem::Requirement
37
23
  requirements:
38
- - - "~>"
24
+ - - '='
39
25
  - !ruby/object:Gem::Version
40
- version: '3.0'
26
+ version: 1.15.0
41
27
  - !ruby/object:Gem::Dependency
42
- name: pubid-core
28
+ name: pubid-ccsds
43
29
  requirement: !ruby/object:Gem::Requirement
44
30
  requirements:
45
- - - "~>"
31
+ - - '='
46
32
  - !ruby/object:Gem::Version
47
- version: 1.12.5
33
+ version: 1.15.0
48
34
  type: :runtime
49
35
  prerelease: false
50
36
  version_requirements: !ruby/object:Gem::Requirement
51
37
  requirements:
52
- - - "~>"
38
+ - - '='
53
39
  - !ruby/object:Gem::Version
54
- version: 1.12.5
40
+ version: 1.15.0
55
41
  - !ruby/object:Gem::Dependency
56
- name: pubid-nist
42
+ name: pubid-cen
57
43
  requirement: !ruby/object:Gem::Requirement
58
44
  requirements:
59
- - - "~>"
45
+ - - '='
60
46
  - !ruby/object:Gem::Version
61
- version: 0.4.0
47
+ version: 1.15.0
62
48
  type: :runtime
63
49
  prerelease: false
64
50
  version_requirements: !ruby/object:Gem::Requirement
65
51
  requirements:
66
- - - "~>"
52
+ - - '='
67
53
  - !ruby/object:Gem::Version
68
- version: 0.4.0
54
+ version: 1.15.0
69
55
  - !ruby/object:Gem::Dependency
70
- name: pubid-iso
56
+ name: pubid-core
71
57
  requirement: !ruby/object:Gem::Requirement
72
58
  requirements:
73
- - - "~>"
59
+ - - '='
74
60
  - !ruby/object:Gem::Version
75
- version: 0.7.5
61
+ version: 1.15.0
76
62
  type: :runtime
77
63
  prerelease: false
78
64
  version_requirements: !ruby/object:Gem::Requirement
79
65
  requirements:
80
- - - "~>"
66
+ - - '='
81
67
  - !ruby/object:Gem::Version
82
- version: 0.7.5
68
+ version: 1.15.0
83
69
  - !ruby/object:Gem::Dependency
84
- name: pubid-ieee
70
+ name: pubid-etsi
85
71
  requirement: !ruby/object:Gem::Requirement
86
72
  requirements:
87
- - - "~>"
73
+ - - '='
88
74
  - !ruby/object:Gem::Version
89
- version: 0.2.2
75
+ version: 1.15.0
90
76
  type: :runtime
91
77
  prerelease: false
92
78
  version_requirements: !ruby/object:Gem::Requirement
93
79
  requirements:
94
- - - "~>"
80
+ - - '='
95
81
  - !ruby/object:Gem::Version
96
- version: 0.2.2
82
+ version: 1.15.0
97
83
  - !ruby/object:Gem::Dependency
98
- name: pubid-cen
84
+ name: pubid-iec
99
85
  requirement: !ruby/object:Gem::Requirement
100
86
  requirements:
101
- - - "~>"
87
+ - - '='
102
88
  - !ruby/object:Gem::Version
103
- version: 0.2.4
89
+ version: 1.15.0
104
90
  type: :runtime
105
91
  prerelease: false
106
92
  version_requirements: !ruby/object:Gem::Requirement
107
93
  requirements:
108
- - - "~>"
94
+ - - '='
109
95
  - !ruby/object:Gem::Version
110
- version: 0.2.4
96
+ version: 1.15.0
111
97
  - !ruby/object:Gem::Dependency
112
- name: pubid-iec
98
+ name: pubid-ieee
113
99
  requirement: !ruby/object:Gem::Requirement
114
100
  requirements:
115
- - - "~>"
101
+ - - '='
116
102
  - !ruby/object:Gem::Version
117
- version: 0.3.1
103
+ version: 1.15.0
118
104
  type: :runtime
119
105
  prerelease: false
120
106
  version_requirements: !ruby/object:Gem::Requirement
121
107
  requirements:
122
- - - "~>"
108
+ - - '='
123
109
  - !ruby/object:Gem::Version
124
- version: 0.3.1
110
+ version: 1.15.0
125
111
  - !ruby/object:Gem::Dependency
126
- name: pubid-ccsds
112
+ name: pubid-iso
127
113
  requirement: !ruby/object:Gem::Requirement
128
114
  requirements:
129
- - - "~>"
115
+ - - '='
130
116
  - !ruby/object:Gem::Version
131
- version: 0.1.3
117
+ version: 1.15.0
132
118
  type: :runtime
133
119
  prerelease: false
134
120
  version_requirements: !ruby/object:Gem::Requirement
135
121
  requirements:
136
- - - "~>"
122
+ - - '='
137
123
  - !ruby/object:Gem::Version
138
- version: 0.1.3
124
+ version: 1.15.0
139
125
  - !ruby/object:Gem::Dependency
140
126
  name: pubid-itu
141
127
  requirement: !ruby/object:Gem::Requirement
142
128
  requirements:
143
- - - "~>"
129
+ - - '='
144
130
  - !ruby/object:Gem::Version
145
- version: 0.1.0
131
+ version: 1.15.0
146
132
  type: :runtime
147
133
  prerelease: false
148
134
  version_requirements: !ruby/object:Gem::Requirement
149
135
  requirements:
150
- - - "~>"
136
+ - - '='
151
137
  - !ruby/object:Gem::Version
152
- version: 0.1.0
138
+ version: 1.15.0
153
139
  - !ruby/object:Gem::Dependency
154
140
  name: pubid-jis
155
141
  requirement: !ruby/object:Gem::Requirement
156
142
  requirements:
157
- - - "~>"
143
+ - - '='
158
144
  - !ruby/object:Gem::Version
159
- version: 0.3.2
145
+ version: 1.15.0
160
146
  type: :runtime
161
147
  prerelease: false
162
148
  version_requirements: !ruby/object:Gem::Requirement
163
149
  requirements:
164
- - - "~>"
150
+ - - '='
165
151
  - !ruby/object:Gem::Version
166
- version: 0.3.2
152
+ version: 1.15.0
167
153
  - !ruby/object:Gem::Dependency
168
- name: pubid-bsi
154
+ name: pubid-nist
169
155
  requirement: !ruby/object:Gem::Requirement
170
156
  requirements:
171
- - - "~>"
157
+ - - '='
172
158
  - !ruby/object:Gem::Version
173
- version: 0.3.4
159
+ version: 1.15.0
174
160
  type: :runtime
175
161
  prerelease: false
176
162
  version_requirements: !ruby/object:Gem::Requirement
177
163
  requirements:
178
- - - "~>"
164
+ - - '='
179
165
  - !ruby/object:Gem::Version
180
- version: 0.3.4
166
+ version: 1.15.0
181
167
  - !ruby/object:Gem::Dependency
182
- name: pubid-etsi
168
+ name: pubid-plateau
183
169
  requirement: !ruby/object:Gem::Requirement
184
170
  requirements:
185
- - - "~>"
171
+ - - '='
186
172
  - !ruby/object:Gem::Version
187
- version: 0.1.0
173
+ version: 1.15.0
188
174
  type: :runtime
189
175
  prerelease: false
190
176
  version_requirements: !ruby/object:Gem::Requirement
191
177
  requirements:
192
- - - "~>"
178
+ - - '='
193
179
  - !ruby/object:Gem::Version
194
- version: 0.1.0
180
+ version: 1.15.0
195
181
  description: Gem including all pubid-* gems.
196
182
  email:
197
183
  - open.source@ribose.com
@@ -210,7 +196,7 @@ homepage: https://github.com/metanorma/pubid
210
196
  licenses:
211
197
  - BSD-2-Clause
212
198
  metadata: {}
213
- post_install_message:
199
+ post_install_message:
214
200
  rdoc_options: []
215
201
  require_paths:
216
202
  - lib
@@ -225,8 +211,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
225
211
  - !ruby/object:Gem::Version
226
212
  version: '0'
227
213
  requirements: []
228
- rubygems_version: 3.3.27
229
- signing_key:
214
+ rubygems_version: 3.5.22
215
+ signing_key:
230
216
  specification_version: 4
231
217
  summary: Gem including all pubid-* gems.
232
218
  test_files: []