TEv2 - generic document structure
This issue specifies the structure of documents that are processable by TEv2 and/or its additions (generator-plugins). When approved, the text may become part of the eSSIF-Lab documentation that describes its terminology management.
Header
Every file starts with a docusaurus header, i.e.
---
id: document-identifier
title: title that will show when the document is rendered
... (other [docusaurus header items](https://v2.docusaurus.io/docs/markdown-features/#markdown-headers))
---
TEv2 specific header attributes
After the regular docusaurus header attributes, additional attributes must be specified that allow TEv2 to properly function. These attributes must be in the same header block as the docusaurus attributes (i.e. in the same block delimited by the ---
lines), as follows:
---
... (docusaurus attributes)
scopeid: <identifier for the scope in which the document is defined>
type: <type of the document>
typeid: <identifier of the individual document (given the values of `scopeid` and `type`)>
---
where:
- scopeid (required) identifies the scope within which the document (and its contents) belongs, and is being defined/updated/...
-
type identifies the kinds of contents that can be expected in the document. The following types are being used (and should be supported):
- scope the file contains the specification/description of a scope.
- concept the file contains the definition of a term and a description of the concept to which it refers;
- term the file contains the definition of a term and a reference to a concept;
- glossary the file contains a specification for the generation of a glossary that is to become part of the same scope to which the glossary-file belongs;
- glossary the file contains a specification for the generation of a dictionary that is to become part of the same scope to which the glossary-file belongs; Additional types may be defined as necessary.
- typeid: text that ensures the triple (scopeid,type,typeid) always identifies the document.
TEv2 Generator-specific attributes
Additional attributes may be added for purposes defined by different generators.
For example:
-
hoverText: <text that pops up when the user hovers over a document-reference>
is used by the documentation website generator, for the purpose of producing a popup when the user hovers over a reference to that document. This text may not include %%-references. -
glossaryText: <text>
is used by the glossary-generator as the explanation of a term. This text MAY contain %%-references where the|
MUST be replaced by the^
character (as the|
character causes errors when it is part of a docusaurus-header). -
stage: <stageid>
is foreseen to be used in ToIP terminology life cycle management processes.
Attributes that are not used by Docusaurus, TEv2 or a generator will be ignored (so you can leave them there if you don't use them).