Merge pull request #1 from henkvancann/main

Role defs altered

spec/36_roles.md

@@ -11,8 +11,11 @@ A clear specification of roles in- and outside an average ToIP "group" might cle
 ### Role: ToIP glossary maintainer
 Uses: Source management tool. Reads and compares concepts in text and terminology in glossaries, (for example generated by Spec-Up) to use within his/hers "own" over-arching ToIP glossary. He/she builds as much consensus around terms and concepts and promotes using the ToIP glossary as reference material.
 
-### Role: Specification author
-Uses: an IDE, git and a browser extension, to edit Spec-Up markdown files for his/her specific context (mental model) in a version managed environment, authenticated, to write the concept and specification and offer this as a PR. He/she uses browser extensions to check technical consistency of the links in the text and harvest a personal collection of term definitions.
+### Role: Specification content author, describing concepts
+Focusses on content of definitions covering concepts of the group he/she belongs to. Uses: an IDE, git and a browser extension, to edit Spec-Up markdown files for his/her specific context (mental model) in a version managed environment, authenticated, to write the concept and specification and offer this as a PR. He/she uses browser extensions to check technical consistency of the links in the text and harvests a personal collection of term definitions.
+
+### Role: Specification terminology author, covering concepts
+Focusses on term definitions covering concepts of the group he/she belongs to. Uses: an IDE, git and a browser extension, to edit Spec-Up markdown files for his/her specific context (mental model) in a version managed environment, authenticated, to write the concept and specification and offer this as a PR. He/she uses browser extensions to check technical consistency of the links in the text and harvests a personal collection of term definitions. Specification author terms that cover those concepts.
 
 ### Role: Curator
 Uses an IDE and git and browser extensions, to check logical consistency & meaning of term definition in a certain context and uses browser extensions to harvest a personal collection of term definitions, based on those recommended by the specification authors.

spec/52_manual_defsrefs.md

@@ -1,4 +1,4 @@
-## User manual defs and refs
+## User manual defs, refs and xrefs
 
 #### Background
 To simplify the job of tech spec construction and editing, the Technology Stack WG has adopted the Spec-Up spec editing tool which is originally a DIF open source project ([here](https://github.com/decentralized-identity/spec-up)). 
@@ -8,7 +8,7 @@ TrustoverIP invests in improving this tool: The [normative section](#spec-up-imp
 #### Objective
 To offer authors and curators a hands-up guide to handle Spec-up's syntax correctly and efficiently with regard to `defs`, `refs` and `xrefs`. Thereby respecting the golden rule:
 
- "try ref before def"
+ "try (x)ref before def"
 
 ([why?](#try-ref-before-def))
 

spec/60_terms_and_definitions.md

@@ -1,44 +1,51 @@
 
-[//]: # (Pandoc Formatting Macros)
+~ [//]: # (Pandoc Formatting Macros)
 
-[//]: # (Portable Document Format)
+~ [//]: # (Portable Document Format)
 
-[//]: # (blank)
+~ [//]: # (blank)
 
-[//]: # (: file format defined by ISO 32000-2)
+~ [//]: # (: file format defined by ISO 32000-2)
 
 [[def: Guide, guide, guidelines]]
- ~ 
-What is the criterium something being a Guide versus a Specification?
-A Specification has enough [[ref: normative]] statements to be directly implementatable. 
+
+~ ~ 
+~ What is the criterium something being a Guide versus a Specification?
+~ A Specification has enough [[ref: normative]] statements to be directly implementatable. 
 
 [[def: normative]]
- ~ 
-A theory is “normative” if it, in some sense, tells you what you should do - what action you should take.Also see [KERISSE](https://weboftrust.github.io/WOT-terms/docs/glossary-unified?level=2#normative)
+
+~ ~ 
+~ A theory is “normative” if it, in some sense, tells you what you should do - what action you should take.Also see [KERISSE](https://weboftrust.github.io/WOT-terms/docs/glossary-unified?level=2#normative)
 
 [[def: phrase]]
+
 ~ Something is a phrase when it's either a [[ref: term]], an [[ref: abbreviation]] or an [[ref: alias]] in the context of this [[ref: guide]].
 
 [[def: term]]
+
 ~ The ToIP notation of a terminology item, that requires a definiton, that could have an abbreviation and zero or more aliasses. A term is supposed to be uniquely defined in a certain scope, but can have many exactly the same instances in a broader community. 
-The term also serves as a key in the source management tool of ToIP terminology sources and to make a comparison among terms. 
-Criterium: only if a certain word or [[ref: phrase]] in ToIP notation and first placed in the definition tag, then it's a term in the scope of this [[ref: guide]]. Only a term can have just one [[ref:abbreviation]]. 
-Also see [term](https://weboftrust.github.io/WOT-terms/docs/glossary-unified?level=2#term).
+~ The term also serves as a key in the source management tool of ToIP terminology sources and to make a comparison among terms. 
+~ Criterium: only if a certain word or [[ref: phrase]] in ToIP notation and first placed in the definition tag, then it's a term in the scope of this [[ref: guide]]. Only a term can have just one [[ref:abbreviation]]. 
+~ Also see [term](https://weboftrust.github.io/WOT-terms/docs/glossary-unified?level=2#term).
 
 [[def: abbrev, abbreviation]]
+
 ~ a shorthand in capitals for a [[ref: term]]. It may contain special characters. It may not contain spaces. 
-Criterium for not being an abbreviation: If the word is not in uppercase, in our context the word is more likely to be an [[ref: alias]] for the term.
+~ Criterium for not being an abbreviation: If the word is not in uppercase, in our context the word is more likely to be an [[ref: alias]] for the term.
 
 [[def: alias]]
+
 ~ Any notation of a terminology item, that is an alternative for a term being defined. The alias also serves as a comparison among term definitions. 
-An alias is typically a means to one-on-one relate specific wording to a term already defined. For example :
-- Synonyms
-- Plural - singular
-- Different spelling
-- Lowercase versus Uppercase 
-- another (!) abbreviation
-*Mind you: the most applicable abbreviation should be in [[ref:abbrev]].*
-Criterium: an alias | TBW |
+~ An alias is typically a means to one-on-one relate specific wording to a term already defined. For example :
+~ - Synonyms
+~ - Plural - singular
+~ - Different spelling
+~ - Lowercase versus Uppercase 
+~ - another (!) abbreviation
+~ *Mind you: the most applicable abbreviation should be in [[ref:abbrev]].*
+~ Criterium: an alias | TBW |
 
 [[def: doctag]]
+
 ~ A short unique tag assigned to the remote Spec-Up document containing the def for the term being referenced. So any Spec-Up document that uses remote refs would need to include a doctag section

spec/glossary-intro-created-by-split-tool.md

@@ -0,0 +1,9 @@
+
+[//]: # (Pandoc Formatting Macros)
+
+[//]: # (Portable Document Format)
+
+[//]: # (blank)
+
+[//]: # (: file format defined by ISO 32000-2)
+

spec/terms-definitions/abbrev.md

@@ -0,0 +1,4 @@
+[[def: abbrev, abbreviation]]
+~ a shorthand in capitals for a [[ref: term]]. It may contain special characters. It may not contain spaces. 
+Criterium for not being an abbreviation: If the word is not in uppercase, in our context the word is more likely to be an [[ref: alias]] for the term.
+

spec/terms-definitions/alias.md

@@ -0,0 +1,11 @@
+[[def: alias]]
+~ Any notation of a terminology item, that is an alternative for a term being defined. The alias also serves as a comparison among term definitions. 
+An alias is typically a means to one-on-one relate specific wording to a term already defined. For example :
+- Synonyms
+- Plural - singular
+- Different spelling
+- Lowercase versus Uppercase 
+- another (!) abbreviation
+*Mind you: the most applicable abbreviation should be in [[ref:abbrev]].*
+Criterium: an alias | TBW |
+

spec/terms-definitions/doctag.md

@@ -0,0 +1,2 @@
+[[def: doctag]]
+~ A short unique tag assigned to the remote Spec-Up document containing the def for the term being referenced. So any Spec-Up document that uses remote refs would need to include a doctag section

spec/terms-definitions/guide.md

@@ -0,0 +1,5 @@
+[[def: Guide, guide, guidelines]]
+ ~ 
+What is the criterium something being a Guide versus a Specification?
+A Specification has enough [[ref: normative]] statements to be directly implementatable. 
+

spec/terms-definitions/normative.md

@@ -0,0 +1,4 @@
+[[def: normative]]
+ ~ 
+A theory is “normative” if it, in some sense, tells you what you should do - what action you should take.Also see [KERISSE](https://weboftrust.github.io/WOT-terms/docs/glossary-unified?level=2#normative)
+

spec/terms-definitions/phrase.md

@@ -0,0 +1,3 @@
+[[def: phrase]]
+~ Something is a phrase when it's either a [[ref: term]], an [[ref: abbreviation]] or an [[ref: alias]] in the context of this [[ref: guide]].
+

spec/terms-definitions/term.md

@@ -0,0 +1,6 @@
+[[def: term]]
+~ The ToIP notation of a terminology item, that requires a definiton, that could have an abbreviation and zero or more aliasses. A term is supposed to be uniquely defined in a certain scope, but can have many exactly the same instances in a broader community. 
+The term also serves as a key in the source management tool of ToIP terminology sources and to make a comparison among terms. 
+Criterium: only if a certain word or [[ref: phrase]] in ToIP notation and first placed in the definition tag, then it's a term in the scope of this [[ref: guide]]. Only a term can have just one [[ref:abbreviation]]. 
+Also see [term](https://weboftrust.github.io/WOT-terms/docs/glossary-unified?level=2#term).
+

specs.json

@@ -1,39 +1 @@
-
-{
- "specs": [
- {
- "title": "ToIP Template Specification",
- "spec_directory": "./spec",
- "output_path": "./docs",
- "markdown_paths": [
- "05_title.md", 
- "10_header.md",
- "13_toc.md",
- "16_foreword.md",
- "18_clauses.md",
- "20_introduction.md",
- "24_scope.md",
- "28_design.md",
- "32_howto_define.md",
- "36_roles.md",
- "40_tools_landscape.md",
- "44_style_guide.md",
- "48_source_management.md",
- "52_manual_defsrefs.md",
- "60_terms_and_definitions.md",
- "64_biblio.md",
- "68_spec-up-improvements.md",
- "72_integration.md",
- "90_annex.md"
- ],
- "logo": "https://raw.githubusercontent.com/trustoverip/logo-assets/master/logos/ToIP-Logo-Color-SolidDimensional-Horizontal-LightOnDark.svg",
- "logo_link": "https://github.com/trustoverip/specification-template",
- "katex": true,
- "source": {
- "host": "github",
- "account": "trustoverip",
- "repo": "specification-template"
- }
- }
- ]
-}
+{"specs":[{"title":"ToIP Template Specification","spec_directory":"./spec","output_path":"./docs","markdown_paths":["05_title.md","10_header.md","13_toc.md","16_foreword.md","18_clauses.md","20_introduction.md","24_scope.md","28_design.md","32_howto_define.md","36_roles.md","40_tools_landscape.md","44_style_guide.md","48_source_management.md","52_manual_defsrefs.md","glossary-intro-created-by-split-tool.md","terms-definitions/guide.md","terms-definitions/normative.md","terms-definitions/phrase.md","terms-definitions/term.md","terms-definitions/abbrev.md","terms-definitions/alias.md","terms-definitions/doctag.md","64_biblio.md","68_spec-up-improvements.md","72_integration.md","90_annex.md"],"logo":"https://raw.githubusercontent.com/trustoverip/logo-assets/master/logos/ToIP-Logo-Color-SolidDimensional-Horizontal-LightOnDark.svg","logo_link":"https://github.com/trustoverip/specification-template","katex":true,"source":{"host":"github","account":"trustoverip","repo":"specification-template"}}]}

terms-unsplit-json

@@ -0,0 +1,39 @@
+
+{
+ "specs": [
+ {
+ "title": "ToIP Template Specification",
+ "spec_directory": "./spec",
+ "output_path": "./docs",
+ "markdown_paths": [
+ "05_title.md", 
+ "10_header.md",
+ "13_toc.md",
+ "16_foreword.md",
+ "18_clauses.md",
+ "20_introduction.md",
+ "24_scope.md",
+ "28_design.md",
+ "32_howto_define.md",
+ "36_roles.md",
+ "40_tools_landscape.md",
+ "44_style_guide.md",
+ "48_source_management.md",
+ "52_manual_defsrefs.md",
+ "60_terms_and_definitions.md",
+ "64_biblio.md",
+ "68_spec-up-improvements.md",
+ "72_integration.md",
+ "90_annex.md"
+ ],
+ "logo": "https://raw.githubusercontent.com/trustoverip/logo-assets/master/logos/ToIP-Logo-Color-SolidDimensional-Horizontal-LightOnDark.svg",
+ "logo_link": "https://github.com/trustoverip/specification-template",
+ "katex": true,
+ "source": {
+ "host": "github",
+ "account": "trustoverip",
+ "repo": "specification-template"
+ }
+ }
+ ]
+}