TEv2 ways of referencing documents
TEv1 way of referencing
In TEv1, documents are referable by the docusaurus mechanism for referencing, i.e. by using the docusaurus id
attribute for referencing, optionally pre-pended by a (relative) path to the dictionary in which the referred-to document lives. For example, a document may refer to a document with attribute id: some-id
by writing %%shown text|some-id%%
, or %%shown text|./some-id%%
.
This mechanism works for terminologies under the assumption that there's only one terminology/scope to deal with.
TEv2 ways of referencing
In TEv2 we need a referencing mechanism that allows us to deal with multiple scopes (namespaces).
Now follows a suggestion for allowed syntax. In this suggestion, when we say 'in the same scope' or 'of the same type', this means 'same as: the document that contains the reference'. The idea of the syntax is that after selecting all documents that satisfy the specified selection criterion, only one document remains. If this is not the case, an error condition exists that should be 'thrown' to the author with a message that allows him to determine what went wrong AND how to fix it.
-
%%shown-text|<typeid>%% selects all documents with attribute
typeid: ` that are in the same scope. -
%%shown-text|<type>-<typeid>%% selects all documents with attributes
type:AND
typeid: ` that are in the same scope. -
%%shown-text|<scopeid>/<typeid>%% selects all documents with attributes
scopeid:AND
typeid: `. -
%%shown-text|<scopeid>/<type>-<typeid>%% selects all documents with attributes
scopeid:AND
type:AND
typeid: `.
Notes:
- this syntax can be extended in future versions by replacing the
<scopeid>
in references by a 'path' of (nested) scopes, and perhaps even by an URI+'path-of-nested-scopes'. - a scopid is NOT a directory(name) per se. It SHOULD be possible to have a mapping between a (nest of) scopes and arbitrary directories, e.g. by means of some JSON object such as
{ "scope-register": [
{ "scopeID": "essifLab"
, "scopename": "eSSIF-Lab"
, "location": "https://gitlab.grnet.gr/essif-lab/framework/terminology"
, "subscopes": [
{ "scopeID": "essifLabTerminology"
, "scopename": "eSSIF-Lab Terminology"
, "location": "https://gitlab.grnet.gr/essif-lab/framework/terminology/terminology"
}]
}]
}
Such a JSON object may be generated from scope-files (.md files that contain scope-data), or by having the admin of the system maintain that JSON object.
TEv2 shorthand references
When writing this text, more than 71% (216/301) of the references in the eSSIF-Lab documentation were of the form %%shown-text|reference-text%%
where shown-text
, after converting it to all lower-case, would equal reference-text
. This percentage rises to over 83% (252/301) if also spaces in shown-text
were converted to -
characters. This makes the case for specifying that %%shown-text%%, provided it only consists of characters {[A-Z], [a-z], '-', ' '}, must be rewritten to
%%shown-text|reference-text%%prior to further processing, where
reference-textis the all-lowercase version of
shown-textwhere every space is replaced by
-` character.
If shown-text
contains characters other than those allowed, an error conditions exists (which must be thrown to the author etc.)