From 04e5093dd81810e93de822e575c26d69aaf9dfdd Mon Sep 17 00:00:00 2001 From: Andreas Martin <6525873+about-code@users.noreply.github.com> Date: Sun, 26 Mar 2023 13:34:48 +0200 Subject: [PATCH] fix: Aliases after term description (#266) * docs: some links fixed --- doc/vocabulary-uris.md | 36 ++++++++++++++++++------------------ lib/terminator.js | 12 +++++++++--- md/doc/vocabulary-uris.md | 10 +++------- 3 files changed, 30 insertions(+), 28 deletions(-) diff --git a/doc/vocabulary-uris.md b/doc/vocabulary-uris.md index bbe2c229..566ebdbb 100644 --- a/doc/vocabulary-uris.md +++ b/doc/vocabulary-uris.md @@ -4,12 +4,6 @@ aliases: Vocabulary URIs --> -[headingIdAlgorithm]: ../README.md#headingidalgorithm - -[doc-import]: ../README.md#structured-export-and-import - -[doc-skos]: ./skos-interop.md - Consider a [term][1] *skin*. In human medicine it's a term for a human organ while in computer science its often used to refer to a software's look and feel. These kinds of *ambiguities* demand *clarification* which is what glossaries are meant for, of course. *A computer program* can't understand a natural language description of a [term][1]'s meaning. What it is good at is comparing and distingushing *symbols*. With unique IDs like @@ -19,11 +13,11 @@ Consider a [term][1] *skin*. In human medicine it's a term for a human organ whi a computer can operate on symbols equivalent to *some meaning* without having to know the exact meaning. Such IDs can then be used, for example, to establish relationships between semantic concepts (like `xID not-equal yID`). Semantic modeling goes beyond glossaries. Assigning glossary terms unique IDs, though, enables using them in other technical implementations of knowledge organization systems such as thesauri, taxonomies or word nets. -**Since v6.0.0** [glossarify-md][2] supports [exporting and importing][doc-import] glossaries (see also [Interoperability with SKOS and JSON-LD][doc-skos]). +**Since v6.0.0** [glossarify-md][2] supports [exporting][3] and [importing][4] glossaries (see also Interoperability with [SKOS 🌎][5] and [JSON-LD 🌎][6]). ## [Vocabulary URIs and Term URIs](#vocabulary-uris-and-term-uris) -`glossaries` entries can be augmented with a `uri` [config option][3] which assigns a glossary a so-called *[vocabulary][4] [URI][5]*. Then on [exporting][6] *[term][1] URIs* can be derived from the vocabulary [URI][7] and a term's *heading ID* by appending the heading ID to the vocabulary URI (see [headingIdAlgorithm] for how [glossarify-md][2] generates heading IDs). +`glossaries` entries can be augmented with a `uri` [config option][7] which assigns a glossary a so-called *[vocabulary][8] [URI][9]*. Then on [exporting][3] *[term][1] URIs* can be derived from the vocabulary [URI][10] and a term's *heading ID* by appending the heading ID to the vocabulary URI (see config option `headingIdAlgorithm`) for how [glossarify-md][2] generates heading IDs). ```json { @@ -37,7 +31,7 @@ a computer can operate on symbols equivalent to *some meaning* without having to } ``` -If you need more control about a [term][1]'s Term [URI][5], then there are two switches you can tweak: +If you need more control about a [term][1]'s Term [URI][9], then there are two switches you can tweak: * providing a custom heading ID using pandoc-style `{#headingId}` * providing a `uri` [term][1] attribute @@ -67,13 +61,13 @@ Term with an individual URI. ### [Resolvability](#resolvability) -URIs can be *just identifiers*. But URIs can also be used to *locate and retrieve* representations of what they identify over a network protocol like HTTPS. For example, a web browser and a [term][1]'s [URI][5] could be used to retrieve an HTML representation with a human readable definition of a term. A `glossaries` entry with `linkUris: true` will make [glossarify-md][2] link term occurrences with a *book-external* authoritative definition on the web rather than with the book-internal glossary. On [imported][doc-import] glossaries `showUris: true` or `showUris: "${uri}"` will render [URI][7] links in the markdown glossary generated from imported terms. +URIs can be *just identifiers*. But URIs can also be used to *locate and retrieve* representations of what they identify over a network protocol like HTTPS. For example, a web browser and a [term][1]'s [URI][9] could be used to retrieve an HTML representation with a human readable definition of a term. A `glossaries` entry with `linkUris: true` will make [glossarify-md][2] link term occurrences with a *book-external* authoritative definition on the web rather than with the book-internal glossary. On imported glossaries `showUris: true` or `showUris: "${uri}"` will render [URI][10] links in the markdown glossary generated from imported terms. ### [Authority](#authority) -URIs for terms 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][5] and make it the identifier of something (like we did in our examples) only the legitimate domain name owner as registered in the Domain Name System (DNS) can claim [authority][8] in case of disputes over some definition. +URIs for terms 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][9] and make it the identifier of something (like we did in our examples) only the legitimate domain name owner as registered in the Domain Name System (DNS) can claim [authority][11] 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][5]. So particularly when publishing a [vocabulary][4] it is usually not a good idea to use someone else's domain. +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][9]. So particularly when publishing a [vocabulary][8] it is usually not a good idea to use someone else's domain. -[headingIdAlgorithm]: ../README.md#headingidalgorithm -[doc-import]: ../README.md#structured-export-and-import -[doc-skos]: ./skos-interop.md - Consider a term *skin*. In human medicine it's a term for a human organ while in computer science its often used to refer to a software's look and feel. These kinds of *ambiguities* demand *clarification* which is what glossaries are meant for, of course. *A computer program* can't understand a natural language description of a term's meaning. What it is good at is comparing and distingushing *symbols*. With unique IDs like @@ -16,11 +12,11 @@ Consider a term *skin*. In human medicine it's a term for a human organ while in a computer can operate on symbols equivalent to *some meaning* without having to know the exact meaning. Such IDs can then be used, for example, to establish relationships between semantic concepts (like `xID not-equal yID`). Semantic modeling goes beyond glossaries. Assigning glossary terms unique IDs, though, enables using them in other technical implementations of knowledge organization systems such as thesauri, taxonomies or word nets. -**Since v6.0.0** glossarify-md supports [exporting and importing][doc-import] glossaries (see also [Interoperability with SKOS and JSON-LD][doc-skos]). +**Since v6.0.0** glossarify-md supports exporting and importing glossaries (see also Interoperability with SKOS and JSON-LD). ## Vocabulary URIs and Term URIs -`glossaries` entries can be augmented with a `uri` config option which assigns a glossary a so-called *vocabulary URI*. Then on exporting *term URIs* can be derived from the vocabulary URI and a term's *heading ID* by appending the heading ID to the vocabulary URI (see [headingIdAlgorithm] for how glossarify-md generates heading IDs). +`glossaries` entries can be augmented with a `uri` config option which assigns a glossary a so-called *vocabulary URI*. Then on exporting *term URIs* can be derived from the vocabulary URI and a term's *heading ID* by appending the heading ID to the vocabulary URI (see config option `headingIdAlgorithm`) for how glossarify-md generates heading IDs). ~~~json { @@ -63,7 +59,7 @@ Term with an individual URI. ### Resolvability -URIs can be *just identifiers*. But URIs can also be used to *locate and retrieve* representations of what they identify over a network protocol like HTTPS. For example, a web browser and a term's URI could be used to retrieve an HTML representation with a human readable definition of a term. A `glossaries` entry with `linkUris: true` will make glossarify-md link term occurrences with a *book-external* authoritative definition on the web rather than with the book-internal glossary. On [imported][doc-import] glossaries `showUris: true` or `showUris: "${uri}"` will render URI links in the markdown glossary generated from imported terms. +URIs can be *just identifiers*. But URIs can also be used to *locate and retrieve* representations of what they identify over a network protocol like HTTPS. For example, a web browser and a term's URI could be used to retrieve an HTML representation with a human readable definition of a term. A `glossaries` entry with `linkUris: true` will make glossarify-md link term occurrences with a *book-external* authoritative definition on the web rather than with the book-internal glossary. On imported glossaries `showUris: true` or `showUris: "${uri}"` will render URI links in the markdown glossary generated from imported terms. ### Authority