feat: New option 'glossaries[].showUris'

README.md

@@ -68,7 +68,7 @@
   - [List of Tables](#list-of-tables)
   - [Lists from Regular Expressions](#lists-from-regular-expressions)
 - [Markdown Syntax Extensions](#markdown-syntax-extensions)
-- [Structured Exports and imports](#structured-exports-and-imports)
+- [Structured Export and Import](#structured-export-and-import)
 - [Node Support Matrix](#node-support-matrix)
 - [Options](#options)
 - [Special Thanks go to](#special-thanks-go-to)
@@ -549,7 +549,7 @@ Use *invisible* HTML anchors to generate lists from and navigate to text content
 
 ```md
 <a id="tutorial-part-1" title="Tutorial Part 1"></a>
-This is not a video tutorial but a textual tutorial. The body of text can be navigated to from a List of Tutorials ans uses the classifier *tutorial*.
+This is not a video tutorial but a textual tutorial. The body of text can be navigated to from a List of Tutorials and uses the classifier *tutorial*.
 ```
 
 > **Note:** If you find the browser not scrolling correctly when navigating lists on GitHub, please read [Addendum: Lists in GitHub Repos](https://github.com/about-code/glossarify-md/blob/master/doc/lists-on-github.md).
@@ -811,7 +811,9 @@ You could also embed the configuration into a *glossarify-md.conf.json* using th
 >
 > Read more on how these projects relate to glossarify-md in our [Addendum: Conceptual Layers](https://github.com/about-code/glossarify-md/blob/master/doc/conceptual-layers.md)
 
-## Structured Exports and imports
+## Structured Export and Import
+
+[doc-export-import]: #structured-export-and-import
 
 [SKOS]: https://w3.org/skos
 
@@ -831,7 +833,7 @@ You could also embed the configuration into a *glossarify-md.conf.json* using th
 }
 ```
 
-When using a glob pattern for the markdown `file` it is possible to export terms from multiple files into a single JSON file. Consider declaring a glossary `uri`. [glossarify-md] will assign each term a web-compatible identifier by combining the glossary's vocabulary `uri` with a term's identifier (see [`headingIdAlgorithm`][headingIdAlgorithm]). Note that URIs are not required to resolve to some web page but *can* do so. More on the idea behind URIs read [here][doc-vocabulary-uris]
+When using a glob pattern for the markdown `file` it is possible to export terms from multiple files into a single JSON file. Consider declaring a glossary `uri`. [glossarify-md] will assign each term a web-compatible identifier by combining the glossary's vocabulary `uri` with a term's identifier (see [`headingIdAlgorithm`][headingIdAlgorithm]). Note that URIs are not required to resolve to some web page but *can* do so. More on the idea behind URIs read [here][doc-vocabulary-uris].
 
 You can import terms the same way using `import` instead.
 
@@ -958,22 +960,30 @@ sequence. If you would like to have the glossary sorted provide a *sort* directi
 - **Range:** `{ file: string [, context: string]} | Array<{ file: string [, context: string]}>`
 - **Since:** v6.0.0
 
-Export markdown terms in a structured JSON format.
+Export markdown terms in a structured JSON format. More read [here][doc-export-import].
 
 #### `glossaries[].import`
 
 - **Range:** `{ file: string [, context: string]}`
 - **Since:** v6.0.0
 
-Import terms from a structured JSON format and generate a markdown glossary from it.
+Import terms from a structured JSON format and generate a markdown glossary from it. More read [here][doc-export-import].
 
 #### `glossaries[].linkUris`
 
 - **Range:** `boolean`
 - **Default:** `false`
 - **Since:** v6.0.0
 
-When true, occurrences of glossary terms found in text will no longer be linked with the markdown glossary file but with an external definition on the web using a term's URI. The given glossary file will serve as a data source for a link title providing a short tooltip and may still be found from [indexFiles](#generatefilesindexfiles).
+When `true`, occurrences of glossary terms found in text will no longer be linked with the markdown glossary file but with an external definition on the web using a term's URI. The given glossary file will serve as a data source for a link title providing a short tooltip and may still be found from [indexFiles](#generatefilesindexfiles).
+
+#### `glossaries[].showUris`
+
+- **Range:** `boolean|string`
+- **Default:** `false`
+- **Since:** v6.0.0
+
+When being `true` or being a template string with a placeholder `${uri}` then render term URIs in glossaries generated from [imported][doc-export-import] terms.
 
 #### `ignoreCase`
 

conf/v5/doc/schema-defs-glossaryfile.md

@@ -61,6 +61,16 @@ If present, sort terms in output glossary. Default: None. See also i18n options.
 | `"asc"`  |             |
 | `"desc"` |             |
 
+## showUris
+
+Whether to render a term's URI in the glossary (currently for imported glossaries, only).
+
+`showUris`
+
+*   is optional
+
+*   Type: merged type ([Details](schema-defs-glossaryfile-properties-showuris.md))
+
 ## termHint
 
 A symbol to append to a link to denote that the term refers to a glossary term.

conf/v5/doc/schema-properties-glossaries-items.md

@@ -61,6 +61,16 @@ If present, sort terms in output glossary. Default: None. See also i18n options.
 | `"asc"`  |             |
 | `"desc"` |             |
 
+## showUris
+
+Whether to render a term's URI in the glossary (currently for imported glossaries, only).
+
+`showUris`
+
+*   is optional
+
+*   Type: merged type ([Details](schema-defs-glossaryfile-properties-showuris.md))
+
 ## termHint
 
 A symbol to append to a link to denote that the term refers to a glossary term.

conf/v5/doc/schema.md

@@ -445,6 +445,16 @@ If present, sort terms in output glossary. Default: None. See also i18n options.
 | `"asc"`  |             |
 | `"desc"` |             |
 
+### showUris
+
+Whether to render a term's URI in the glossary (currently for imported glossaries, only).
+
+`showUris`
+
+*   is optional
+
+*   Type: merged type ([Details](schema-defs-glossaryfile-properties-showuris.md))
+
 ### termHint
 
 A symbol to append to a link to denote that the term refers to a glossary term.

conf/v5/schema.json

@@ -188,6 +188,14 @@
                     ,"type": "string"
                     ,"enum": ["asc", "desc"]
                 }
+                ,"showUris": {
+                    "description": "Whether to render a term's URI in the glossary (currently for imported glossaries, only)."
+                    ,"oneOf": [
+                        { "type": "boolean"}
+                        ,{ "type": "string" }
+                    ]
+                    ,"since": "6.0.0"
+                }
                 ,"termHint": {
                     "description": "A symbol to append to a link to denote that the term refers to a glossary term."
                     ,"type": "string"

doc/skos-interop.md

@@ -24,7 +24,7 @@
 
 ### [Exporting SKOS](#exporting-skos)
 
-[glossarify-md's][glossarify-md] export format embeds a [JSON-LD] `@context` document, by default. It maps glossarify-md's own *export model* terminology onto [SKOS] and [Dublin Core][DC] model terms for interoperability with tools supporting [SKOS🟉][2], Dublin Core (optional) and [JSON-LD🟉][1]. You can embed your own JSON-LD `@context` mappings if you need to, though, using `export` with `context`:
+[glossarify-md's][glossarify-md] export format embeds a [JSON-LD] `@context` document, by default. It maps glossarify-md's own *export model* terminology onto [SKOS] and [Dublin Core][DC] model terms for interoperability with tools supporting [SKOS🟉][2], Dublin Core (optional) and [JSON-LD🟉][1]. You can embed your own JSON-LD `@context` mappings if you need to using `export` with `context`:
 
 ```json
 {

doc/vocabulary-uris.md

@@ -4,6 +4,10 @@
 
 [headingidalgorithm]: ../README.md#headingidalgorithm
 
+[iana-urns]: https://www.iana.org/assignments/urn-namespaces/urn-namespaces.xhtml
+
+[doc-import]: ../README.md#structured-export-and-import
+
 **Since v6.0.0** [glossarify-md] supports an `uri` option for glossaries (*vocabulary [URI🟉][1]*):
 
 ```json
@@ -15,7 +19,7 @@
 }
 ```
 
-With the `uri` option [glossarify-md] maps terms onto identifiers using the vocabulary [URI🟉][1] as a base URI for appending a term's heading ID (see [headingidalgorithm]). Exceptions to this rule are possible with the `uri` term attribute:
+With the `uri` *config option* [glossarify-md] maps terms onto identifiers using the vocabulary [URI🟉][1] as a base URI for appending a term's heading ID (see [headingidalgorithm]). Exceptions to this rule are possible with the `uri` *term attribute*:
 
 *glossary.md*
 
@@ -32,9 +36,7 @@ Term with an individual URI.
 
 Consider bankers and IT professionals talking about *security*. Since the term is used differently in the banking domain than it is used in computer science its *ambiguity* can cause some confusion among these people. As a consequence the term demands *clarification* of its particular meaning when being used. That's what glossaries are meant for, of course. Technically such kind of clarification can be achieved using IDs to uniquely identify *one particular definition of meaning*.
 
-Uniform Resource Identifiers (URIs) do fit very well for that purpose. For example whenever we use the [URI🟉][1] `https://banking-example.com/vocab/#security` it is clear that we refer to the meaning defined by `banking-example.com` and when using `https://it-example.com/vocab/#security` we refer to the meaning defined by `it-example.com`.
-
-While anyone could use any domain name in an [URI🟉][1] and make it the identifier of something, only the legitimate domain name owner as registered by the domain name system can claim authority in case of disputes over some definition.
+Uniform Resource Identifiers (URIs) do fit very well for that purpose. For example whenever we use the [URI🟉][1] `https://example.com/vocab/banking/#security` it is clear that we refer to a different meaning than some identifier `https://example.com/vocab/it/#security`.
 
 While not a requirement as a *publisher* you might enjoy that URIs could be used to *locate and retrieve* technical representations of a term definition over a network protocol like HTTP. For example a web browser could be used to locate and retrieve an HTML representation that can be rendered in the browser. Other representations (data formats) are possible, of course, e.g.
 
@@ -43,7 +45,29 @@ While not a requirement as a *publisher* you might enjoy that URIs could be used
 *   a structured JSON representation
 *   and so forth...
 
-If you have a background in Linked Data and Semantic Web technologies you might also interested in reading about [SKOS Interoperability with JSON-LD][2].
+If you have a background in Linked Data and Semantic Web technologies you might also be interested in reading about [SKOS Interoperability with JSON-LD][2].
+
+#### [Authority](#authority)
+
+URIs also reveal the authoritative source for a particular definition, which in our example was `example.com`. While anyone could use any domain name in an [URI🟉][1] and make it the identifier of something (like we did here) only the legitimate domain name owner as registered in the Domain Name System (DNS) can claim authority in case of disputes over some definition. So in this particular example we could *not* veto if the owners of domain `example.com` chose to use above URIs to identify something else. By using another domain name than our own we effectively accept that there could be conflicting definitions wiping out the purpose of an URI. So particularly when publishing a vocabulary it is usually not a good idea to do so.
+
+You can use `linkUris: true` config option of a `glossaries` entry to link term occurrences found in a glossarified markdown book with their *book-external* authoritative definition on the web. With `linkUris: false` (default) glossarify-md will link term occurrences internally within the book. On [imported][doc-import] glossaries you can set `showUris: true` or `showUris: "${uri}"` to render term URIs in the generated markdown glossary.
+
+<!--
+Uniform Resource Names (URNs) may be an alternative to URIs. They do not depend on the Domain Name System as a registry but on an [IANA registry of *URN namespaces*][iana-urns]:
+
+*URN with the `isbn` namespace registered by the International ISBN Agency*
+~~~
+urn:isbn:978-951-0-18435-6
+~~~
+
+It is not as easy to register a URN namespace than it is to register a domain name. But there are a few namespaces representing *ID algorithms*. Particularly the UUID namespace represents elements identified by the open and standardized *Universally Unique Identifier* (RFC 4122). UUIDs can be produced by anyone and the `uuid` namespace can be used with any UUID in the world:
+
+*URN with the `uuid` namespace*
+~~~
+urn:uuid:b3c38d70-3887-11ec-a63d-779a5e093fff
+~~~
+-->
 
 [1]: ./glossary.md#uri "Uniform Resource Identifier and Uniform Resource Locator describe both the same thing, which is an ID with a syntax scheme://authority.tld/path/#fragment?query like https://my.org/foo/#bar?q=123."
 

lib/importer.js

@@ -48,19 +48,20 @@ export function importGlossaries(context) {
     const {baseDir, glossaries} = context.conf;
     return Promise
         .all(glossaries.map(glossConf => {
-            const importConf = glossConf.import;
-            if (! (importConf && glossConf.file)) {
+            const { file, showUris, import: importConf } = glossConf;
+            if (! (importConf && file)) {
                 return Promise.resolve();
             }
+
             const jsonImportFile    = importConf.file    ? path.resolve(baseDir, importConf.file)    : "";
             const jsonldContextFile = importConf.context ? path.resolve(baseDir, importConf.context) : "";
             return readJsonFile(jsonImportFile)
                 .then(importedObj => parseJsonLd(importedObj, jsonldContextFile))
                 .then(glossaryObj => {
                     try {
                         const vFile = new VFile({
-                            path: glossConf.file
-                            ,value: json2md(glossaryObj)
+                            path: file
+                            ,value: json2md(glossaryObj, { showUris })
                         });
                         glossConf.uri = glossaryObj.uri;
                         glossConf.title = glossaryObj.title;
@@ -211,31 +212,31 @@ function ldValue(v) {
 
 // ============ SERIALIZING (to Markdown) ============
 
-function json2md(imported) {
+function json2md(imported, opts) {
+    const { showUris } = opts;
     const terms = imported.terms || {};
     const termsStr = Object
         .keys(terms)
-        .reduce(getTermReducer(terms), "");
+        .reduce(getTermReducer(terms, showUris), "");
 
     const glossaryStr = `# ${imported.title || "Glossary" }\n${termsStr}`;
     return glossaryStr;
 }
 
-function getTermReducer(terms) {
+function getTermReducer(terms, showUris) {
     return function (prev, uri) {
         const { label = "", definition = "", aliases = [] } = terms[uri];
-        const attrs = {
-            uri: uri
-            ,aliases: aliases.join(", ") || undefined
-        };
-        const termAttrs = ["<!--", JSON.stringify(attrs, null, 2), "-->"].join("");
+        const attrs = { uri: uri, aliases: aliases.join(", ") || undefined };
+        const termAttrs = `<!--${JSON.stringify(attrs, null, 2)}-->`;
+        const showUri = showUris
+            ? `\n\n${ showUris === true ? uri : showUris.replace("${uri}", uri) }`
+            : "";
         if (label) {
             const md = prev +
 `
 ## ${label}
 ${termAttrs}
-
-${definition}
+${definition}${showUri}
 `;
             return md;
         } else {

lib/model/glossary.js

@@ -31,6 +31,9 @@ export class Glossary {
         /** @type {boolean} */
         this.linkUris = data.linkUris || false;
 
+        /** @type {boolean} */
+        this.showUris = data.showUris || false;
+
         /** @type {string} */
         this.termHint = data.termHint || "";
 

md/README.md

@@ -765,6 +765,7 @@ You could also embed the configuration into a *glossarify-md.conf.json* using th
 > Read more on how these projects relate to glossarify-md in our [Addendum: Conceptual Layers](https://github.com/about-code/glossarify-md/blob/master/doc/conceptual-layers.md)
 
 ## Structured Export and Import
+[doc-export-import]: #structured-export-and-import
 [SKOS]: https://w3.org/skos
 
 **Since v6.0.0** terms in a markdown glossary can be exported to a structured JSON format.
@@ -885,7 +886,8 @@ Generates a list of tables.
     termHint: string,
     sort: string],
     uri: string,
-    linkUri: string,
+    linkUris: boolean,
+    showUris: boolean|string,
     import: {},
     export: {},
   }
@@ -905,22 +907,30 @@ sequence. If you would like to have the glossary sorted provide a *sort* directi
 - **Range:** `{ file: string [, context: string]} | Array<{ file: string [, context: string]}>`
 - **Since:** v6.0.0
 
-Export markdown terms in a structured JSON format.
+Export markdown terms in a structured JSON format. More read [here][doc-export-import].
 
 #### `glossaries[].import`
 
 - **Range:** `{ file: string [, context: string]}`
 - **Since:** v6.0.0
 
-Import terms from a structured JSON format and generate a markdown glossary from it.
+Import terms from a structured JSON format and generate a markdown glossary from it. More read [here][doc-export-import].
 
 #### `glossaries[].linkUris`
 
 - **Range:** `boolean`
 - **Default:** `false`
 - **Since:** v6.0.0
 
-When true, occurrences of glossary terms found in text will no longer be linked with the markdown glossary file but with an external definition on the web using a term's URI. The given glossary file will serve as a data source for a link title providing a short tooltip and may still be found from [indexFiles](#generatefilesindexfiles).
+When `true`, occurrences of glossary terms found in text will no longer be linked with the markdown glossary file but with an external definition on the web using a term's URI. The given glossary file will serve as a data source for a link title providing a short tooltip and may still be found from [indexFiles](#generatefilesindexfiles).
+
+#### `glossaries[].showUris`
+
+- **Range:** `boolean|string`
+- **Default:** `false`
+- **Since:** v6.0.0
+
+When being `true` or being a template string with a placeholder `${uri}` then render term URIs in glossaries generated from [imported][doc-export-import] terms.
 
 #### `ignoreCase`