Skip to content

Commit

Permalink
fix: Aliases after term description (#266)
Browse files Browse the repository at this point in the history 
* docs: some links fixed
  • Loading branch information
@about-code
about-code authored Mar 26, 2023
1 parent 410c7f0 commit 04e5093
Show file tree
Hide file tree
Showing 3 changed files with 30 additions and 28 deletions.
36 changes: 18 additions & 18 deletions doc/vocabulary-uris.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
{
Expand All @@ -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
Expand Down Expand Up @@ -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.

<!--
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*:
Expand All @@ -95,14 +89,20 @@ urn:uuid:b3c38d70-3887-11ec-a63d-779a5e093fff

[2]: https://github.com/about-code/glossarify-md

[3]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md
[3]: https://github.com/about-code/glossarify-md/blob/master/doc/export.md#export "Since v6.0.0 Exporting makes glossarify-md generate and write a structured representation of a markdown glossary to the output directory."

[4]: https://github.com/about-code/glossarify-md/blob/master/doc/import.md#importing-terms "⚠ Important: glossarify-md is able to import terms and definitions from a remote location using https."

[5]: http://w3.org/skos/ "With the Simple Knowledge Organization System (SKOS) the World Wide Web Consortium (W3C) has standardized a (meta-)vocabulary which is suited and intended for modeling Simple Knowledge Organization Systems such as Glossaries, Thesauri, Taxonomies or Word Nets."

[6]: https://json-ld.org "JSON-LD is a standardized JSON document format for mapping system-specific terms of a JSON-based data format to well-know terms from public vocabularies."

[4]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#vocabulary "A collection of terms which is uniquely identifiable."
[7]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md

[5]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#uri--url "Uniform Resource Identifier and Uniform Resource Locator are 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."
[8]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#vocabulary "A collection of terms which is uniquely identifiable."

[6]: https://github.com/about-code/glossarify-md/blob/master/doc/export.md#export "Since v6.0.0 Exporting makes glossarify-md generate and write a structured representation of a markdown glossary to the output directory."
[9]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#uri--url "Uniform Resource Identifier and Uniform Resource Locator are 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."

[7]: https://github.com/about-code/glossarify-md/blob/master/doc/term-attributes.md#uri "A unique identifier for the term and the definition of it's meaning."
[10]: https://github.com/about-code/glossarify-md/blob/master/doc/term-attributes.md#uri "A unique identifier for the term and the definition of it's meaning."

[8]: https://github.com/about-code/glossarify-md/blob/master/doc/vocabulary-uris.md#authority "URIs for terms reveal the authoritative source for a particular definition, which in our example was example.com."
[11]: https://github.com/about-code/glossarify-md/blob/master/doc/vocabulary-uris.md#authority "URIs for terms reveal the authoritative source for a particular definition, which in our example was example.com."
12 changes: 9 additions & 3 deletions lib/terminator.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ function getNodeVisitor(context, glossVFile) {

const State = {};
State.AWAIT_HEADING = 2;
State.AWAIT_ALIAS = 4;
State.AWAIT_HTML_COMMENT = 4;
State.AWAIT_PARAGRAPH = 8;
State.active = State.AWAIT_HEADING;
State.is = (state) => State.active & state;
Expand Down Expand Up @@ -72,12 +72,12 @@ function getNodeVisitor(context, glossVFile) {
,ignoreCase: ignoreCase
});
node.children.unshift(termNode);
State.next(State.AWAIT_PARAGRAPH | State.AWAIT_ALIAS);
State.next(State.AWAIT_PARAGRAPH | State.AWAIT_HTML_COMMENT);
} else {
State.next(State.AWAIT_HEADING);
}
} else if (
State.is(State.AWAIT_ALIAS)
State.is(State.AWAIT_HTML_COMMENT)
&& isHtmlComment(node)
) {
const htmlComment = node.value;
Expand All @@ -88,6 +88,7 @@ function getNodeVisitor(context, glossVFile) {
&& node.type === "paragraph"
) {
termNode.appendDescription(getNodeText(node));
State.next(State.AWAIT_PARAGRAPH); // [1]
} else if (
!State.is(State.AWAIT_PARAGRAPH)
&& node.type === "paragraph"
Expand All @@ -97,6 +98,11 @@ function getNodeVisitor(context, glossVFile) {
return;
}
};

// Implementation Notes:
// [1]: We may have entered this branch awaiting state (AWAIT_PARAGRAPH | AWAIT_HTML_COMMENT)
// but once we've entered a paragraph we should no longer await an alias anymore
// but only further paragraphs.
}

function getTermUri(context, glossVFile, headingId) {
Expand Down
10 changes: 3 additions & 7 deletions md/doc/vocabulary-uris.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,6 @@
aliases: Vocabulary URIs
-->

[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
Expand All @@ -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
{
Expand Down Expand Up @@ -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

Expand Down

0 comments on commit 04e5093

Please sign in to comment.