From 9dc677d7baae52cd6f73bde5b53921d619416be0 Mon Sep 17 00:00:00 2001 From: bruce-esrig Date: Thu, 27 Mar 2025 21:00:36 -0400 Subject: [PATCH 01/20] Add draft explanation What is a Glossary? --- website/docs/explanation/glossary_what.md | 82 +++++++++++++++++++++++ website/docs/explanation/index.md | 1 + 2 files changed, 83 insertions(+) create mode 100644 website/docs/explanation/glossary_what.md diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md new file mode 100644 index 0000000..8506ec3 --- /dev/null +++ b/website/docs/explanation/glossary_what.md @@ -0,0 +1,82 @@ +# What is a glossary? + +## Purpose + +This topic will provide background information on glossaries: +* What they are for +* How they are structured +* What advanced features are available + +## What is a glossary? + +A *glossary* gives the meanings of *terms* in a work or domain. +It is presented as a list of terms in alphabetic order, each with a *gloss* that explains the term. + +Each explanation gives the reader enough understanding to become familiar, and perhaps even comfortable, with the term. + +Simplicity is prized. As a rule of thumb, a glossary entry should make the reader one step more comfortable with the term. + +## Structural features + +### Simple definition + +A definition is a statement of fact that conveys the meaning of a term. +A definition that consists of a simple phrase or sentence may be all the explanation that is needed. + +**core**
+The working memory of a computer. + +When a formal style is used, the item being defined is omitted from the beginning of the explanation. + +### Abbreviation + +If the term is an abbreviation, the gloss starts with its expansion. The abbreviation is explained briefly after its expansion. + +**DNS**
+**Domain Name System**. A system that translates human-readable domain names (canonical.com) to their IP addresses (185.125.190.20). + +### Abbreviation (conversational) + +A more conversational style is sometimes used, especially when the expansion of an abbreviation can be read as the subject of the gloss. + +**FC**
+Fiber Channel (FC) is a storage networking protocol used for low-latency communication between a storage device and a node +in a Storage Area Network (SAN). + +In this definition of FC, expansions are followed by abbreviations as is customary in running text. +This is a good way to handle abbreviations such as FC and SAN that are comparatively specialized. + +### Cross-references + +Cross-references help readers navigate among related terms. + +#### A casual mention of another term + +If the gloss for a term discusses a second term, the second term should be linked. + +**DDNS*
+**Dynamic Domain Name System**. A service that automatically updates {term}`DNS` records when the underlying IP address changes (aka, dynamic IP). + +#### A term that provides depth or broader context + +When a concept that provides depth or broader context is used in a gloss, it can be linked using "See". + +**DIT**
+**Directory Information Tree**. In directory services (See {term}`LDAP`), a hierarchical tree-like structure used to organize and store information. + +#### A related topic + +A collection of related topics can be provided at the end of the gloss. + +**GnuTLS**
+**GNU’s Not Unix Transport Layer Security**. A GNU software package that secures data in transit by implementing the {term}`SSL`, {term}`TLS`, and {term}`DTLS` protocols. + +Related topic(s): [GnuTLS (Ubuntu Server documentation)](https://documentation.ubuntu.com/server/explanation/crypto/gnutls/#), [GnuTLS (official site)](https://www.gnutls.org/), Cryptography, Web services, OpenLDAP. + +## Advanced features + +In this treatement, the features considered basic are those focused on meaning. + +There is an additional realm of glossary features that are focused on terminology management. Sometimes the origin of a term, or the pronunciation, or an alternate form, or some other aspect of the term is of great interest. + +Advanced features can be introduced in glossaries by imitating the features of entries in authoritative dictionaries. diff --git a/website/docs/explanation/index.md b/website/docs/explanation/index.md index 2449ee0..b02fef9 100644 --- a/website/docs/explanation/index.md +++ b/website/docs/explanation/index.md @@ -5,5 +5,6 @@ :glob: :maxdepth: 1 +What is a glossary About the Academy ``` From 2a2b0d75bc704f8109135ab762c3d02a53cfe990 Mon Sep 17 00:00:00 2001 From: bruce-esrig Date: Thu, 27 Mar 2025 21:52:11 -0400 Subject: [PATCH 02/20] Corrected errors ... note that there's no glossary (yet?), so the term refs couldn't be live. --- website/.custom_wordlist.txt | 15 +++++++++++++++ website/conf.py | 2 +- website/docs/explanation/glossary_what.md | 14 +++++++++----- 3 files changed, 25 insertions(+), 6 deletions(-) diff --git a/website/.custom_wordlist.txt b/website/.custom_wordlist.txt index 70334b3..0a1359a 100644 --- a/website/.custom_wordlist.txt +++ b/website/.custom_wordlist.txt @@ -8,9 +8,17 @@ bootable Ceph CLA Ctrl +DDNS +DIT DITA +DNS +DNS docsacademy +DTLS +FC +Fiber freesewing +GnuTLS golang howto https @@ -18,6 +26,7 @@ IoT JIRA KDE LaTeX +LDAP lifecycle MAAS MDX @@ -27,7 +36,10 @@ Multipass Netplan ODA onboarding +OpenLDAP OpenStack +organize +prized PRs rebase rebasing @@ -36,5 +48,8 @@ repos RST scalable Snapcraft +specialized SSL +TLS WSL + diff --git a/website/conf.py b/website/conf.py index de78ab7..166f3f8 100644 --- a/website/conf.py +++ b/website/conf.py @@ -140,7 +140,7 @@ # Docs location in the repo; used in links for viewing the source files # # TODO: To customise the directory, uncomment and update as needed. - "github_folder": "/website/", + "repo_folder": "/website/", # TODO: To enable or disable the Previous / Next buttons at the bottom of pages # Valid options: none, prev, next, both # "sequential_nav": "both", diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index 8506ec3..b34bfdf 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -54,28 +54,32 @@ Cross-references help readers navigate among related terms. If the gloss for a term discusses a second term, the second term should be linked. -**DDNS*
-**Dynamic Domain Name System**. A service that automatically updates {term}`DNS` records when the underlying IP address changes (aka, dynamic IP). + + + + +**DDNS**
+**Dynamic Domain Name System**. A service that automatically updates (term-ref) *DNS* records when the underlying IP address changes (aka, dynamic IP). #### A term that provides depth or broader context When a concept that provides depth or broader context is used in a gloss, it can be linked using "See". **DIT**
-**Directory Information Tree**. In directory services (See {term}`LDAP`), a hierarchical tree-like structure used to organize and store information. +**Directory Information Tree**. In directory services (See (term-ref) *LDAP*), a hierarchical tree-like structure used to organize and store information. #### A related topic A collection of related topics can be provided at the end of the gloss. **GnuTLS**
-**GNU’s Not Unix Transport Layer Security**. A GNU software package that secures data in transit by implementing the {term}`SSL`, {term}`TLS`, and {term}`DTLS` protocols. +**GNU’s Not Unix Transport Layer Security**. A GNU software package that secures data in transit by implementing the (term-ref) *SSL*, (term-ref) *TLS*, and (term-ref) *DTLS* protocols. Related topic(s): [GnuTLS (Ubuntu Server documentation)](https://documentation.ubuntu.com/server/explanation/crypto/gnutls/#), [GnuTLS (official site)](https://www.gnutls.org/), Cryptography, Web services, OpenLDAP. ## Advanced features -In this treatement, the features considered basic are those focused on meaning. +In this treatment, the features considered basic are those focused on meaning. There is an additional realm of glossary features that are focused on terminology management. Sometimes the origin of a term, or the pronunciation, or an alternate form, or some other aspect of the term is of great interest. From d08fbc5cec85f8f05b5fae02654df0a9172d7d56 Mon Sep 17 00:00:00 2001 From: bruce-esrig Date: Thu, 27 Mar 2025 23:08:54 -0400 Subject: [PATCH 03/20] Caught up w oda/main. Fixed typo in links for authors. Updated custom spelling file. --- website/.custom_wordlist.txt | 5 ++++- website/library/reference/links-for-technical-writers.md | 2 +- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/website/.custom_wordlist.txt b/website/.custom_wordlist.txt index 0a1359a..8a9c327 100644 --- a/website/.custom_wordlist.txt +++ b/website/.custom_wordlist.txt @@ -5,14 +5,15 @@ AngularJS AsciiDoc backends bootable +Center Ceph CLA +Coursera Ctrl DDNS DIT DITA DNS -DNS docsacademy DTLS FC @@ -20,6 +21,7 @@ Fiber freesewing GnuTLS golang +Hackmamba howto https IoT @@ -49,6 +51,7 @@ RST scalable Snapcraft specialized +specializes SSL TLS WSL diff --git a/website/library/reference/links-for-technical-writers.md b/website/library/reference/links-for-technical-writers.md index 84baf18..59dc75c 100644 --- a/website/library/reference/links-for-technical-writers.md +++ b/website/library/reference/links-for-technical-writers.md @@ -20,7 +20,7 @@ - [Google Style Guides](https://google.github.io/styleguide/): guides on style for languages from AngularJS to Vim script. - [Diátaxis](https://diataxis.fr/): a systematic approach to technical documentation authoring. - [Introduction to DITA](https://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part3-all-inclusive/archSpec/base/introduction-to-dita.html#introduction-to-dita): an open standard and architecture for technical information. -- [Technical Writing Resources](https://developers.google.com/tech-writing/resources): resources and style guides from Google for developerss. +- [Technical Writing Resources](https://developers.google.com/tech-writing/resources): resources and style guides from Google for developers. - [What is a Technical Writer Style Guide? With Examples](https://document360.com/blog/technical-writer-style-guide/): guide with style examples from Document360. ## Frameworks From cecd913c7d2ac4811ba2a902171d01d32c85abb3 Mon Sep 17 00:00:00 2001 From: bruce-esrig Date: Wed, 2 Apr 2025 07:57:08 -0400 Subject: [PATCH 04/20] Added mini-glossaries. Removed some excess headings. --- website/docs/explanation/glossary_what.md | 61 ++++++++++++----------- 1 file changed, 31 insertions(+), 30 deletions(-) diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index b34bfdf..5fad6f8 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -1,30 +1,23 @@ # What is a glossary? -## Purpose - -This topic will provide background information on glossaries: -* What they are for -* How they are structured -* What advanced features are available - -## What is a glossary? - A *glossary* gives the meanings of *terms* in a work or domain. It is presented as a list of terms in alphabetic order, each with a *gloss* that explains the term. Each explanation gives the reader enough understanding to become familiar, and perhaps even comfortable, with the term. -Simplicity is prized. As a rule of thumb, a glossary entry should make the reader one step more comfortable with the term. +Simplicity is prized. A glossary entry should aim to make the reader one step more comfortable with the term. -## Structural features +## Structure -### Simple definition +### Definition A definition is a statement of fact that conveys the meaning of a term. A definition that consists of a simple phrase or sentence may be all the explanation that is needed. -**core**
-The working memory of a computer. +```{glossary} +core + The working memory of a computer. +``` When a formal style is used, the item being defined is omitted from the beginning of the explanation. @@ -32,16 +25,20 @@ When a formal style is used, the item being defined is omitted from the beginnin If the term is an abbreviation, the gloss starts with its expansion. The abbreviation is explained briefly after its expansion. -**DNS**
-**Domain Name System**. A system that translates human-readable domain names (canonical.com) to their IP addresses (185.125.190.20). +```{glossary} +DNS + **Domain Name System**. A system that translates human-readable domain names (canonical.com) to their IP addresses (185.125.190.20). +``` ### Abbreviation (conversational) A more conversational style is sometimes used, especially when the expansion of an abbreviation can be read as the subject of the gloss. -**FC**
-Fiber Channel (FC) is a storage networking protocol used for low-latency communication between a storage device and a node -in a Storage Area Network (SAN). +```{glossary} +FC + Fiber Channel (FC) is a storage networking protocol used for low-latency communication between a storage device and a node + in a Storage Area Network (SAN). +``` In this definition of FC, expansions are followed by abbreviations as is customary in running text. This is a good way to handle abbreviations such as FC and SAN that are comparatively specialized. @@ -50,30 +47,34 @@ This is a good way to handle abbreviations such as FC and SAN that are comparati Cross-references help readers navigate among related terms. -#### A casual mention of another term - If the gloss for a term discusses a second term, the second term should be linked. -**DDNS**
-**Dynamic Domain Name System**. A service that automatically updates (term-ref) *DNS* records when the underlying IP address changes (aka, dynamic IP). - -#### A term that provides depth or broader context +```{glossary} +DDNS + **Domain Name System**. + A service that automatically updates :term:`DNS` records when the underlying IP address changes (aka, dynamic IP). +``` When a concept that provides depth or broader context is used in a gloss, it can be linked using "See". -**DIT**
-**Directory Information Tree**. In directory services (See (term-ref) *LDAP*), a hierarchical tree-like structure used to organize and store information. +```{glossary} +DIT + **Directory Information Tree**. In directory services (See :term:`LDAP`), a hierarchical tree-like structure used to organize and store information. +``` #### A related topic A collection of related topics can be provided at the end of the gloss. -**GnuTLS**
-**GNU’s Not Unix Transport Layer Security**. A GNU software package that secures data in transit by implementing the (term-ref) *SSL*, (term-ref) *TLS*, and (term-ref) *DTLS* protocols. +```{glossary} +GnuTLS + **GNU’s Not Unix Transport Layer Security**. + A GNU software package that secures data in transit by implementing the :term:`SSL`, :term:`TLS`, and :term:`DTLS` protocols. +``` Related topic(s): [GnuTLS (Ubuntu Server documentation)](https://documentation.ubuntu.com/server/explanation/crypto/gnutls/#), [GnuTLS (official site)](https://www.gnutls.org/), Cryptography, Web services, OpenLDAP. @@ -81,6 +82,6 @@ Related topic(s): [GnuTLS (Ubuntu Server documentation)](https://documentation.u In this treatment, the features considered basic are those focused on meaning. -There is an additional realm of glossary features that are focused on terminology management. Sometimes the origin of a term, or the pronunciation, or an alternate form, or some other aspect of the term is of great interest. +There is a further realm of glossary features that are focused on terminology management. Sometimes the origin of a term, or the pronunciation, or an alternate form, or some other aspect of the term is of great interest. Advanced features can be introduced in glossaries by imitating the features of entries in authoritative dictionaries. From 2e938260e33640adfa855719e0104c0e5109e28e Mon Sep 17 00:00:00 2001 From: bruce-esrig Date: Wed, 2 Apr 2025 08:04:01 -0400 Subject: [PATCH 05/20] Deleting another two excess headings. --- website/docs/explanation/glossary_what.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index 5fad6f8..9c92146 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -30,8 +30,6 @@ DNS **Domain Name System**. A system that translates human-readable domain names (canonical.com) to their IP addresses (185.125.190.20). ``` -### Abbreviation (conversational) - A more conversational style is sometimes used, especially when the expansion of an abbreviation can be read as the subject of the gloss. ```{glossary} @@ -66,8 +64,6 @@ DIT **Directory Information Tree**. In directory services (See :term:`LDAP`), a hierarchical tree-like structure used to organize and store information. ``` -#### A related topic - A collection of related topics can be provided at the end of the gloss. ```{glossary} From 4ce203b165118e1116ae5e7b3b7cdff975944c66 Mon Sep 17 00:00:00 2001 From: bruce-esrig Date: Thu, 3 Apr 2025 15:50:45 -0400 Subject: [PATCH 06/20] Add appendices for mechanics and locally-defined terms. rST and MyST markup not working. --- website/.custom_wordlist.txt | 8 ++- website/conf.py | 1 - website/docs/explanation/glossary_what.md | 62 ++++++++++++++++++++--- 3 files changed, 61 insertions(+), 10 deletions(-) diff --git a/website/.custom_wordlist.txt b/website/.custom_wordlist.txt index 8a9c327..49ea14a 100644 --- a/website/.custom_wordlist.txt +++ b/website/.custom_wordlist.txt @@ -8,8 +8,11 @@ bootable Center Ceph CLA +connectionless Coursera Ctrl +Datagram +datagram DDNS DIT DITA @@ -31,6 +34,7 @@ LaTeX LDAP lifecycle MAAS +md MDX mentorship MicroStack @@ -47,12 +51,14 @@ rebase rebasing repo repos +reStructured RST +rST scalable Snapcraft specialized specializes SSL TLS +UDP WSL - diff --git a/website/conf.py b/website/conf.py index 166f3f8..a9b4b7d 100644 --- a/website/conf.py +++ b/website/conf.py @@ -209,7 +209,6 @@ # myst_enable_extensions = set() - # Custom Sphinx extensions; see # https://www.sphinx-doc.org/en/master/usage/extensions/index.html diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index 9c92146..d22015e 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -19,8 +19,6 @@ core The working memory of a computer. ``` -When a formal style is used, the item being defined is omitted from the beginning of the explanation. - ### Abbreviation If the term is an abbreviation, the gloss starts with its expansion. The abbreviation is explained briefly after its expansion. @@ -30,16 +28,17 @@ DNS **Domain Name System**. A system that translates human-readable domain names (canonical.com) to their IP addresses (185.125.190.20). ``` -A more conversational style is sometimes used, especially when the expansion of an abbreviation can be read as the subject of the gloss. +In a conversational style, the definition has more of the structure and tone of a spoken sentence. +For example, the definition may begin by repeating the term being defined. ```{glossary} FC - Fiber Channel (FC) is a storage networking protocol used for low-latency communication between a storage device and a node + **Fiber Channel** is a storage networking protocol used for low-latency communication between a storage device and a node in a Storage Area Network (SAN). ``` -In this definition of FC, expansions are followed by abbreviations as is customary in running text. -This is a good way to handle abbreviations such as FC and SAN that are comparatively specialized. +In this definition of FC, the abbreviation SAN is preceded by its expansion as is customary in running text. +This is a good way to handle abbreviations that may be unfamiliar or have not yet been formally defined. ### Cross-references @@ -70,9 +69,10 @@ A collection of related topics can be provided at the end of the gloss. GnuTLS **GNU’s Not Unix Transport Layer Security**. A GNU software package that secures data in transit by implementing the :term:`SSL`, :term:`TLS`, and :term:`DTLS` protocols. -``` -Related topic(s): [GnuTLS (Ubuntu Server documentation)](https://documentation.ubuntu.com/server/explanation/crypto/gnutls/#), [GnuTLS (official site)](https://www.gnutls.org/), Cryptography, Web services, OpenLDAP. + Related topic(s): [GnuTLS (Ubuntu Server documentation)](https://documentation.ubuntu.com/server/explanation/crypto/gnutls/#), [GnuTLS (official site)](https://www.gnutls.org/), Cryptography, Web services, OpenLDAP. + +``` ## Advanced features @@ -81,3 +81,49 @@ In this treatment, the features considered basic are those focused on meaning. There is a further realm of glossary features that are focused on terminology management. Sometimes the origin of a term, or the pronunciation, or an alternate form, or some other aspect of the term is of great interest. Advanced features can be introduced in glossaries by imitating the features of entries in authoritative dictionaries. + +## Appendix 1: Mechanics + +This document is written in the following hierarchy of languages (high to low): +* Markedly Structured Text ([MyST](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#syntax-glossaries)) +* reStructured Text (rST) +* Markdown (md) + +A reference to a term is coded as follows: :: + + :term:`referenced_term` + +A complex glossary entry is coded as follows: :: + + ```{glossary} + GnuTLS_example + **GNU’s Not Unix Transport Layer Security**. + A GNU software package that secures data in transit by implementing the :term:`SSL`, :term:`TLS`, and :term:`DTLS` protocols. + + Related topic(s): [GnuTLS (Ubuntu Server documentation)](https://documentation.ubuntu.com/server/explanation/crypto/gnutls/#), [GnuTLS (official site)](https://www.gnutls.org/), Cryptography, Web services, OpenLDAP. + + ``` + +## Appendix 2: Locally-defined terms + +These terms are referenced within the topic to illustrate cross-references. + +```{glossary} +datagram + In networking, a self-contained, independent packet sent over a network. + A datagram can be routed from source to destination without relying on earlier or subsequent transfers. + +DTLS + **Datagram Transport Layer Security**. A protocol that provides security for :term:`datagram`-based communication, such as UDP. + DTLS offers security features similar to TLS, but is adapted because datagram protocols are connectionless. + +LDAP + **Lightweight Directory Access Protocol**. + +SSL + **Secure Socket Layer**. + +TLS + **Transport Layer Security**. + +``` From e986bac079ef5e983a93ed7b8bf2d100d069b601 Mon Sep 17 00:00:00 2001 From: Bruce Esrig Date: Tue, 15 Apr 2025 18:48:18 -0400 Subject: [PATCH 07/20] Update website/docs/explanation/glossary_what.md Example of a simple definition. Co-authored-by: Sally --- website/docs/explanation/glossary_what.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index d22015e..44a9dfe 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -12,7 +12,7 @@ Simplicity is prized. A glossary entry should aim to make the reader one step mo ### Definition A definition is a statement of fact that conveys the meaning of a term. -A definition that consists of a simple phrase or sentence may be all the explanation that is needed. +A definition that consists of a simple phrase or sentence may be all the explanation that is needed. For example: ```{glossary} core From 79c53826c71d6c3b401f696905319543e406921f Mon Sep 17 00:00:00 2001 From: Bruce Esrig Date: Tue, 15 Apr 2025 18:50:02 -0400 Subject: [PATCH 08/20] Update website/docs/explanation/glossary_what.md Expansions of abbreviations. Co-authored-by: Sally --- website/docs/explanation/glossary_what.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index 44a9dfe..dfd885b 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -21,7 +21,7 @@ core ### Abbreviation -If the term is an abbreviation, the gloss starts with its expansion. The abbreviation is explained briefly after its expansion. +If the term is an abbreviation, the gloss starts with the expanded form of the term. The abbreviation is explained briefly after this expansion. For example: ```{glossary} DNS From f9c4ded412e9540fbbc039ad38fa2665e9bd8cee Mon Sep 17 00:00:00 2001 From: Bruce Esrig Date: Tue, 15 Apr 2025 18:51:21 -0400 Subject: [PATCH 09/20] Update website/docs/explanation/glossary_what.md MyST {term} ref Co-authored-by: Sally --- website/docs/explanation/glossary_what.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index dfd885b..825e160 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -53,7 +53,7 @@ If the gloss for a term discusses a second term, the second term should be linke ```{glossary} DDNS **Domain Name System**. - A service that automatically updates :term:`DNS` records when the underlying IP address changes (aka, dynamic IP). + A service that automatically updates {term}`DNS` records when the underlying IP address changes (aka, dynamic IP). ``` When a concept that provides depth or broader context is used in a gloss, it can be linked using "See". From 5d08c72e41b8adf1d575e9b0c39090745f604e31 Mon Sep 17 00:00:00 2001 From: Bruce Esrig Date: Tue, 15 Apr 2025 18:52:22 -0400 Subject: [PATCH 10/20] Update website/docs/explanation/glossary_what.md MyST {term} ref Co-authored-by: Sally --- website/docs/explanation/glossary_what.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index 825e160..b30fb03 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -60,7 +60,7 @@ When a concept that provides depth or broader context is used in a gloss, it can ```{glossary} DIT - **Directory Information Tree**. In directory services (See :term:`LDAP`), a hierarchical tree-like structure used to organize and store information. + **Directory Information Tree**. In directory services (See {term}`LDAP`), a hierarchical tree-like structure used to organize and store information. ``` A collection of related topics can be provided at the end of the gloss. From 0b7f8091195528f4717a50478e19559676a94998 Mon Sep 17 00:00:00 2001 From: Bruce Esrig Date: Tue, 15 Apr 2025 18:56:16 -0400 Subject: [PATCH 11/20] Update website/docs/explanation/glossary_what.md Where related topics may occur. Co-authored-by: Sally --- website/docs/explanation/glossary_what.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index b30fb03..dff1d17 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -63,7 +63,7 @@ DIT **Directory Information Tree**. In directory services (See {term}`LDAP`), a hierarchical tree-like structure used to organize and store information. ``` -A collection of related topics can be provided at the end of the gloss. +A collection of related topics can be provided at the end of the gloss. These could link elsewhere in the documentation, or to external resources. ```{glossary} GnuTLS From dc1494c263d7f94dfc8b05fdfc14e82e432738b4 Mon Sep 17 00:00:00 2001 From: Bruce Esrig Date: Tue, 15 Apr 2025 18:58:03 -0400 Subject: [PATCH 12/20] Update website/docs/explanation/glossary_what.md MyST {term} ref Co-authored-by: Sally --- website/docs/explanation/glossary_what.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index dff1d17..cdc3d07 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -68,7 +68,7 @@ A collection of related topics can be provided at the end of the gloss. These co ```{glossary} GnuTLS **GNU’s Not Unix Transport Layer Security**. - A GNU software package that secures data in transit by implementing the :term:`SSL`, :term:`TLS`, and :term:`DTLS` protocols. + A GNU software package that secures data in transit by implementing the {term}`SSL`, {term}`TLS`, and {term}`DTLS` protocols. Related topic(s): [GnuTLS (Ubuntu Server documentation)](https://documentation.ubuntu.com/server/explanation/crypto/gnutls/#), [GnuTLS (official site)](https://www.gnutls.org/), Cryptography, Web services, OpenLDAP. From d197584c17883fdbc6c8f35651b01eed6b463c5b Mon Sep 17 00:00:00 2001 From: Bruce Esrig Date: Tue, 15 Apr 2025 18:59:31 -0400 Subject: [PATCH 13/20] Update website/docs/explanation/glossary_what.md nix "terminology management" as too complex Co-authored-by: Sally --- website/docs/explanation/glossary_what.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index cdc3d07..f6a4ca6 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -78,7 +78,7 @@ GnuTLS In this treatment, the features considered basic are those focused on meaning. -There is a further realm of glossary features that are focused on terminology management. Sometimes the origin of a term, or the pronunciation, or an alternate form, or some other aspect of the term is of great interest. +There is a further realm of more specialized glossary features. Sometimes the origin of a term, or the pronunciation, or an alternate form, or some other aspect of the term is of great interest. Advanced features can be introduced in glossaries by imitating the features of entries in authoritative dictionaries. From 26dbeaf99c7c75601a6e8c81f59b1c2d17fde6d2 Mon Sep 17 00:00:00 2001 From: Bruce Esrig Date: Tue, 15 Apr 2025 19:01:58 -0400 Subject: [PATCH 14/20] Update website/docs/explanation/glossary_what.md MyST {term} ref Co-authored-by: Sally --- website/docs/explanation/glossary_what.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index f6a4ca6..7a78d2c 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -91,7 +91,7 @@ This document is written in the following hierarchy of languages (high to low): A reference to a term is coded as follows: :: - :term:`referenced_term` +`{term}`referenced_term`` A complex glossary entry is coded as follows: :: From 6d67e4bd5ed956e144207b68f360c5db56e26200 Mon Sep 17 00:00:00 2001 From: Bruce Esrig Date: Tue, 15 Apr 2025 19:03:35 -0400 Subject: [PATCH 15/20] Update website/docs/explanation/glossary_what.md Explain options MyST vs RST. Co-authored-by: Sally --- website/docs/explanation/glossary_what.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index 7a78d2c..50e6988 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -84,10 +84,9 @@ Advanced features can be introduced in glossaries by imitating the features of e ## Appendix 1: Mechanics -This document is written in the following hierarchy of languages (high to low): -* Markedly Structured Text ([MyST](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#syntax-glossaries)) -* reStructured Text (rST) -* Markdown (md) +This document is written in Markedly Structured Text ([MyST](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#syntax-glossaries)). + +Glossaries can also be produced using [reStructured Text (rST)](https://sublime-and-sphinx-guide.readthedocs.io/en/latest/glossary.html). A reference to a term is coded as follows: :: From fbaecec52892a7a0d7cbcf887530bfe5fb10d60d Mon Sep 17 00:00:00 2001 From: Bruce Esrig Date: Tue, 15 Apr 2025 19:05:51 -0400 Subject: [PATCH 16/20] Update website/docs/explanation/glossary_what.md Use md code block Co-authored-by: Sally --- website/docs/explanation/glossary_what.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index 50e6988..71ff392 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -88,7 +88,7 @@ This document is written in Markedly Structured Text ([MyST](https://myst-parser Glossaries can also be produced using [reStructured Text (rST)](https://sublime-and-sphinx-guide.readthedocs.io/en/latest/glossary.html). -A reference to a term is coded as follows: :: +A reference to a term is coded as follows: `{term}`referenced_term`` From 6f650a38a448c2f8331dfdd440971e1268bb724d Mon Sep 17 00:00:00 2001 From: Bruce Esrig Date: Tue, 15 Apr 2025 19:06:29 -0400 Subject: [PATCH 17/20] Update website/docs/explanation/glossary_what.md Use md code block. Co-authored-by: Sally --- website/docs/explanation/glossary_what.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index 71ff392..28e2813 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -92,7 +92,7 @@ A reference to a term is coded as follows: `{term}`referenced_term`` -A complex glossary entry is coded as follows: :: +A complex glossary entry is coded as follows: ```{glossary} GnuTLS_example From 2d726e583182467c9164e911a65bdfa5433fe8dc Mon Sep 17 00:00:00 2001 From: Bruce Esrig Date: Tue, 15 Apr 2025 19:07:13 -0400 Subject: [PATCH 18/20] Update website/docs/explanation/glossary_what.md Use MyST {term} refs Co-authored-by: Sally --- website/docs/explanation/glossary_what.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index 28e2813..c8d552a 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -97,7 +97,7 @@ A complex glossary entry is coded as follows: ```{glossary} GnuTLS_example **GNU’s Not Unix Transport Layer Security**. - A GNU software package that secures data in transit by implementing the :term:`SSL`, :term:`TLS`, and :term:`DTLS` protocols. + A GNU software package that secures data in transit by implementing the {term}`SSL`, {term}`TLS`, and {term}`DTLS` protocols. Related topic(s): [GnuTLS (Ubuntu Server documentation)](https://documentation.ubuntu.com/server/explanation/crypto/gnutls/#), [GnuTLS (official site)](https://www.gnutls.org/), Cryptography, Web services, OpenLDAP. From 9af28daf00073e60c73ae4d5eecf66adfae8e89e Mon Sep 17 00:00:00 2001 From: Bruce Esrig Date: Tue, 15 Apr 2025 19:07:52 -0400 Subject: [PATCH 19/20] Update website/docs/explanation/glossary_what.md Use MyST {term} ref Co-authored-by: Sally --- website/docs/explanation/glossary_what.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index c8d552a..37c0533 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -113,7 +113,7 @@ datagram A datagram can be routed from source to destination without relying on earlier or subsequent transfers. DTLS - **Datagram Transport Layer Security**. A protocol that provides security for :term:`datagram`-based communication, such as UDP. + **Datagram Transport Layer Security**. A protocol that provides security for {term}`datagram`-based communication, such as UDP. DTLS offers security features similar to TLS, but is adapted because datagram protocols are connectionless. LDAP From d7ecba1af9348451ea2b6478483bee1d235207a3 Mon Sep 17 00:00:00 2001 From: "bruce.esrig" Date: Tue, 15 Apr 2025 20:44:28 -0400 Subject: [PATCH 20/20] Use 4-space indentation for quoted markup. Explain glossary entry < dict entry. --- website/docs/explanation/glossary_what.md | 38 ++++++++++++----------- 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/website/docs/explanation/glossary_what.md b/website/docs/explanation/glossary_what.md index 37c0533..e55b32c 100644 --- a/website/docs/explanation/glossary_what.md +++ b/website/docs/explanation/glossary_what.md @@ -68,40 +68,42 @@ A collection of related topics can be provided at the end of the gloss. These co ```{glossary} GnuTLS **GNU’s Not Unix Transport Layer Security**. - A GNU software package that secures data in transit by implementing the {term}`SSL`, {term}`TLS`, and {term}`DTLS` protocols. + A GNU software package that secures data in transit by implementing the + {term}`SSL`, {term}`TLS`, and {term}`DTLS` protocols. - Related topic(s): [GnuTLS (Ubuntu Server documentation)](https://documentation.ubuntu.com/server/explanation/crypto/gnutls/#), [GnuTLS (official site)](https://www.gnutls.org/), Cryptography, Web services, OpenLDAP. + Related topic(s): [GnuTLS (Ubuntu Server documentation)](https://documentation.ubuntu.com/server/explanation/crypto/gnutls/#), + [GnuTLS (official site)](https://www.gnutls.org/), + Cryptography, Web services, OpenLDAP. ``` -## Advanced features +## Dictionary features -In this treatment, the features considered basic are those focused on meaning. - -There is a further realm of more specialized glossary features. Sometimes the origin of a term, or the pronunciation, or an alternate form, or some other aspect of the term is of great interest. - -Advanced features can be introduced in glossaries by imitating the features of entries in authoritative dictionaries. +Glossary entries tend to be simpler than full dictionary entries. Some glossary entries, however, may include dictionary features such as the origin of a term, or the pronunciation, or an alternate form, or some other specialized aspect of the term that is of great interest. ## Appendix 1: Mechanics -This document is written in Markedly Structured Text ([MyST](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#syntax-glossaries)). +This document is written in Markedly Structured Text +([MyST](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#syntax-glossaries)). Glossaries can also be produced using [reStructured Text (rST)](https://sublime-and-sphinx-guide.readthedocs.io/en/latest/glossary.html). A reference to a term is coded as follows: -`{term}`referenced_term`` - -A complex glossary entry is coded as follows: + `{term}`referenced_term - ```{glossary} - GnuTLS_example - **GNU’s Not Unix Transport Layer Security**. - A GNU software package that secures data in transit by implementing the {term}`SSL`, {term}`TLS`, and {term}`DTLS` protocols. +A complex glossary entry is coded as follows ("..." indicates omitted characters): - Related topic(s): [GnuTLS (Ubuntu Server documentation)](https://documentation.ubuntu.com/server/explanation/crypto/gnutls/#), [GnuTLS (official site)](https://www.gnutls.org/), Cryptography, Web services, OpenLDAP. + ```{glossary} + GnuTLS_example + **GNU’s Not Unix Transport Layer Security**. + A GNU software package that secures data in transit by implementing the + {term}`SSL`, {term}`TLS`, and {term}`DTLS` protocols. - ``` + Related topic(s): [GnuTLS (Ubuntu Server doc...)](https://doc.../gnutls/#), + [GnuTLS (official site)](https://www.gnutls.org/), + Cryptography, Web services, OpenLDAP. + ``` ## Appendix 2: Locally-defined terms