From adbd2b4e7cd31c5564b7e1a8cc56f9385a07e5a4 Mon Sep 17 00:00:00 2001 From: apenzk Date: Tue, 14 Jan 2025 12:21:16 +0100 Subject: [PATCH] rewrite MG and glossary definition --- MG/mg-0/README.md | 11 +++++++-- MIP/mip-15/README.md | 58 +++++++++++++++++++++++++++++++------------- mg-template.md | 11 +++++++-- 3 files changed, 59 insertions(+), 21 deletions(-) diff --git a/MG/mg-0/README.md b/MG/mg-0/README.md index ae18c157..20bd6136 100644 --- a/MG/mg-0/README.md +++ b/MG/mg-0/README.md @@ -1,21 +1,28 @@ # MG-0: gloss -- **Authors**: [Liam Monninger](liam@movementlabs.xyz) +- **Authors**: [Liam Monninger](liam@movementlabs.xyz) +- **Introducing Document: [MIP-0](../../MIP/mip-0/README.md)** A short description of a term as would feature as an entry in a glossary. +## Gloss + +A **gloss** is a short description of a term as would feature as an entry in a glossary. + ### Related Work + 1. [Merriam-Webster's Definition of "gloss"](https://www.merriam-webster.com/dictionary/gloss) ### Example Usages + 1. He updated the **gloss** to include a more detailed explanation. -### Errata +### Changelog \ No newline at end of file diff --git a/MIP/mip-15/README.md b/MIP/mip-15/README.md index 77c4e8a1..fb53bfb4 100644 --- a/MIP/mip-15/README.md +++ b/MIP/mip-15/README.md @@ -1,48 +1,72 @@ # MIP-15: MG (Movement Gloss) -- **Description**: Introduces the Movement Gloss (MG) document type and establishes a process for introducing new glossary terms. Introduces the [Glossary](../GLOSSARY.md), which contains an overview of all terms defined through MGs. + +- **Description**: Terms should be well defined. This is achieved through the [Glossary](../GLOSSARY.md) and the Movement Gloss (MG) process. - **Authors**: [Liam Monninger](mailto:liam@movementlabs.xyz) - **Reviewer**: Andreas Penzkofer - **Desiderata**: [MD-15](../MD/md-15/README.md) ## Abstract -This MIP introduces the Movement Gloss (MG) document type and establishes a process for introducing new glossary terms. The MG document type will be used to define terms unique to Movement Labs and to provide specific definitions for terms that are used in a unique way, underspecified in the literature, or have a specific meaning in the context of Movement Labs. +This MIP defines the [Glossary](../GLOSSARY.md), which contains an overview of relevant terms used in this repo. This glossary defines terms that are frequently used. + +Furthermore, this MIP introduces the Movement Gloss (MG) document type and establishes a process for introducing new glossary terms. The MG document type will be used to define terms unique to Movement Labs and to provide specific definitions for terms that are used in a unique way, underspecified in the literature, or have a specific meaning in the context of Movement Labs. ## Motivation -In order to communicate with more specificity in all contexts, Movement Labs should introduce a glossary. This glossary should define terms both unique to Movement Labs and general terms that are used in a unique way, underspecified in the literature, or have a specific meaning in the context of Movement Labs. +In order to communicate with more specificity in all contexts, Movement Labs should introduce a glossary. We require alignment of terms across this repository and beyond. + +Furthermore, terms may be underspecified in literature, are used in a unique way, or have a specific meaning in the context of Movement Labs. These terms may require additional extensive definition. This necessitates the introduction of the Movement Gloss (MG) document type. ## Specification -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174. +> _The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174._ ### Glossary -The [Glossary](../GLOSSARY.md) is an alphabetically ordered list of terms defined through MGs. Any term introduced through an MG MUST be declared in the Glossary. +The [Glossary](../../GLOSSARY.md) is an alphabetically ordered list of terms that should be defined and may be frequently referenced. The glossary should be a living document that is updated as new terms are introduced or as terms are redefined. + +The Glossary file contains: -The Glossary table contains the following columns: - The Term - A short definition -- The number of the MG that introduces the term +- (Optional) The number of the MG/MIP/MD that introduces the term. -### MG Document Type -A template for the MG is provided at [mg-template](../../md-template.md). An example MG is provided at [mg-0](../../MG/mg-0/README.md). These templates cover the requested elements listed in [MD-15.D1](../MD/md-15/README.md). +The format is as follows (example): -### MG Process -1. A new glossary term MUST be defined in an MG document matching the provided templates. -2. An MG document MUST not be accepted unless justified in an MIP. +```markdown +**Term** + → [MD-x](MG/md-x/README.md) +``` -For example, herein, we justify the introduction of [MG-0](../../MG/mg-0/README.md). MG-0 defines the term "gloss" which is used in the context of Movement Labs to denote the definition of a term as would feature as an entry in a glossary. It is important to include in the glossary both clarify as the acronym "MG" and to provide an example gloss. +### MG (Movement Gloss) -## Reference Implementation -See the MG document type template at [mg-template](../../md-template.md) and the example MG at [mg-0](../../MG/mg-0/README.md). +An MG is a definition of a term that requires detailed explanation. Any term introduced through an MG MUST be declared in the Glossary. +A template for the MG is provided at [mg-template](../../md-template.md). The template covers the requested elements listed in [MD-15.D1](../MD/md-15/README.md). -## Verification +An example MG is provided at [mg-0](../../MG/mg-0/README.md). +An MG document MUST not be accepted unless it is required by an MIP or MD. For example, herein, we justify the introduction of [MG-0](../../MG/mg-0/README.md). MG-0 defines the term "gloss" which is used in the context of Movement Labs to denote the definition of a term as would feature as an entry in a glossary. For the MGs, it is important to include in the glossary both clarify as the acronym "MG" and to provide an example gloss. +#### MG Structure -## Errata +**Related Work** +Enumerate key usages of the term or related terms in other contexts. + +**Example Usages** +Provide examples of the term's usage in context. +**Changelog** +Document any post-publication changes to the glossary entry. + +## Reference Implementation + +See the [Glossary](../../GLOSSARY.md). + +See the MG document type template at [mg-template](../../md-template.md) and the example MG at [mg-0](../../MG/mg-0/README.md). + +## Verification + +## Errata ## Appendix diff --git a/mg-template.md b/mg-template.md index b7c9b031..d9be5960 100644 --- a/mg-template.md +++ b/mg-template.md @@ -1,11 +1,16 @@ # MG-\: \ + - **Authors**: [Author](mailto:author@email.com) +- **Introducing Document: [MIP/MD-\](../MIP/mip-\/README.md)** + +## \ ### Related Work + @@ -14,6 +19,7 @@ 3. [Reference 3](https://example.com) ### Example Usages + @@ -21,7 +27,8 @@ 2. Example 2 3. Example 3 -### Errata +### Changelog + \ No newline at end of file