|
| 1 | +# What is a glossary? |
| 2 | + |
| 3 | +A *glossary* gives the meanings of *terms* in a work or domain. |
| 4 | +It is presented as a list of terms in alphabetic order, each with a *gloss* that explains the term. |
| 5 | + |
| 6 | +Each explanation gives the reader enough understanding to become familiar, and perhaps even comfortable, with the term. |
| 7 | + |
| 8 | +Simplicity is prized. A glossary entry should aim to make the reader one step more comfortable with the term. |
| 9 | + |
| 10 | +## Structure |
| 11 | + |
| 12 | +### Definition |
| 13 | + |
| 14 | +A definition is a statement of fact that conveys the meaning of a term. |
| 15 | +A definition that consists of a simple phrase or sentence may be all the explanation that is needed. For example: |
| 16 | + |
| 17 | +```{glossary} |
| 18 | +core |
| 19 | + The working memory of a computer. |
| 20 | +``` |
| 21 | + |
| 22 | +### Abbreviation |
| 23 | + |
| 24 | +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: |
| 25 | + |
| 26 | +```{glossary} |
| 27 | +DNS |
| 28 | + **Domain Name System**. A system that translates human-readable domain names (canonical.com) to their IP addresses (185.125.190.20). |
| 29 | +``` |
| 30 | + |
| 31 | +In a conversational style, the definition has more of the structure and tone of a spoken sentence. |
| 32 | +For example, the definition may begin by repeating the term being defined. |
| 33 | + |
| 34 | +```{glossary} |
| 35 | +FC |
| 36 | + **Fiber Channel** is a storage networking protocol used for low-latency communication between a storage device and a node |
| 37 | + in a Storage Area Network (SAN). |
| 38 | +``` |
| 39 | + |
| 40 | +In this definition of FC, the abbreviation SAN is preceded by its expansion as is customary in running text. |
| 41 | +This is a good way to handle abbreviations that may be unfamiliar or have not yet been formally defined. |
| 42 | + |
| 43 | +### Cross-references |
| 44 | + |
| 45 | +Cross-references help readers navigate among related terms. |
| 46 | + |
| 47 | +If the gloss for a term discusses a second term, the second term should be linked. |
| 48 | + |
| 49 | +<!-- {term}`DNS` replaced by *DNS* --> |
| 50 | +<!-- other terms: LDAP, SSL, TLS, DTLS --> |
| 51 | + |
| 52 | + |
| 53 | +```{glossary} |
| 54 | +DDNS |
| 55 | + **Domain Name System**. |
| 56 | + A service that automatically updates {term}`DNS` records when the underlying IP address changes (aka, dynamic IP). |
| 57 | +``` |
| 58 | + |
| 59 | +When a concept that provides depth or broader context is used in a gloss, it can be linked using "See". |
| 60 | + |
| 61 | +```{glossary} |
| 62 | +DIT |
| 63 | + **Directory Information Tree**. In directory services (See {term}`LDAP`), a hierarchical tree-like structure used to organize and store information. |
| 64 | +``` |
| 65 | + |
| 66 | +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. |
| 67 | + |
| 68 | +```{glossary} |
| 69 | +GnuTLS |
| 70 | + **GNU’s Not Unix Transport Layer Security**. |
| 71 | + A GNU software package that secures data in transit by implementing the |
| 72 | + {term}`SSL`, {term}`TLS`, and {term}`DTLS` protocols. |
| 73 | +
|
| 74 | + Related topic(s): [GnuTLS (Ubuntu Server documentation)](https://documentation.ubuntu.com/server/explanation/crypto/gnutls/#), |
| 75 | + [GnuTLS (official site)](https://www.gnutls.org/), |
| 76 | + Cryptography, Web services, OpenLDAP. |
| 77 | +
|
| 78 | +``` |
| 79 | + |
| 80 | +## Dictionary features |
| 81 | + |
| 82 | +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. |
| 83 | + |
| 84 | +## Appendix 1: Mechanics |
| 85 | + |
| 86 | +This document is written in Markedly Structured Text |
| 87 | +([MyST](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#syntax-glossaries)). |
| 88 | + |
| 89 | +Glossaries can also be produced using [reStructured Text (rST)](https://sublime-and-sphinx-guide.readthedocs.io/en/latest/glossary.html). |
| 90 | + |
| 91 | +A reference to a term is coded as follows: |
| 92 | + |
| 93 | + `{term}`referenced_term |
| 94 | + |
| 95 | +A complex glossary entry is coded as follows ("..." indicates omitted characters): |
| 96 | + |
| 97 | + ```{glossary} |
| 98 | + GnuTLS_example |
| 99 | + **GNU’s Not Unix Transport Layer Security**. |
| 100 | + A GNU software package that secures data in transit by implementing the |
| 101 | + {term}`SSL`, {term}`TLS`, and {term}`DTLS` protocols. |
| 102 | + |
| 103 | + Related topic(s): [GnuTLS (Ubuntu Server doc...)](https://doc.../gnutls/#), |
| 104 | + [GnuTLS (official site)](https://www.gnutls.org/), |
| 105 | + Cryptography, Web services, OpenLDAP. |
| 106 | + ``` |
| 107 | + |
| 108 | +## Appendix 2: Locally-defined terms |
| 109 | + |
| 110 | +These terms are referenced within the topic to illustrate cross-references. |
| 111 | + |
| 112 | +```{glossary} |
| 113 | +datagram |
| 114 | + In networking, a self-contained, independent packet sent over a network. |
| 115 | + A datagram can be routed from source to destination without relying on earlier or subsequent transfers. |
| 116 | +
|
| 117 | +DTLS |
| 118 | + **Datagram Transport Layer Security**. A protocol that provides security for {term}`datagram`-based communication, such as UDP. |
| 119 | + DTLS offers security features similar to TLS, but is adapted because datagram protocols are connectionless. |
| 120 | +
|
| 121 | +LDAP |
| 122 | + **Lightweight Directory Access Protocol**. |
| 123 | +
|
| 124 | +SSL |
| 125 | + **Secure Socket Layer**. |
| 126 | +
|
| 127 | +TLS |
| 128 | + **Transport Layer Security**. |
| 129 | +
|
| 130 | +``` |
0 commit comments