Update: building up the new glossary

[s-makin]

The problem

Now that we have a glossary, we need to begin defining the terms.

What is needed

Since the glossary was based on the spelling exceptions list I have made a first pass to clear out the spelling exceptions, duplicates, and plural items. However, there are still plenty of terms that don't belong there, and all terms need to be defined. Some terms/acryonyms may have more than one definition.

• Each valid term in the glossary needs a clear definition.
• Invalid terms need to be removed.
• Once a term has a definition, it needs to be referencedlinked in any pages that use that term (at the first place on each page that the term appears).

What's a valid term?

• Acronyms
• Product or package names (definition of the spelling and capitalization should come from the official product documentation)
• Technical terms/jargon

What's an invalid term?

• Code elements/terms that only appear in code blocks without a corresponding textual definition
• A plural of a term that's already been defined
• A duplicate of a term with alternative spelling
• Terms that only appear in the glossary page

Suggestions

I don't recommend trying to tackle the entire list in one PR, it's very long and would be a lot for one person to do alone! Pick a subset of terms you want to define (I suggest no more than 5-10 in one go).

• For each term, search in the rendered documentation to see which page(s) it appears in - you'll want to make a note of those for later.

  • If it's an invalid term, it can be deleted from the glossary list.
  • If it only has a single definition/meaning, include the definition in the glossary - it's fine to pick this up from the documentation. Feel free to link to other supporting material (such as manual pages or official package documentation) as you see fit.
  • It it has more than one meaning, make sure to include all possible definitions.

• It would be great to also refer to the section/topic the term relates to (e.g. ACLs are related to security, but also pops up in the OpenLDAP and Kerberos content). This will help in the future, as we may want to provide section-specific glossaries, or organise the glossary into sections.

• Finally, after you have defined the term, include a reference to the glossary entry on each page where the term appears, using the MyST syntax:

  {term}`glossary term to link to`
  

  The term inside the backticks needs to match the glossary term exactly. But, if you want to point to a term with a different link text, you can use the following syntax instead:

  {term}`Acess Control Lists <ACL>`
  

  Where in this example, "Acess Control Lists" is the link text shown to the user, and ACL is the term as it appears in the glossary.

• The terms only need to be linked to the glossary the first time they appear on each page (i.e., you don't need to link every appearance).

Related to

• New content: add a glossary #5

[network-charles]

I had to explicitly reference the glossary because on the page, the word was singular, but on the glossary, it was plural.

For example:
Page
fallback

Glossary
fallbacks

If you would like to resolve this, you can do this.

{term}`fallback <fallbacks>`

The syntax is this.

{term}`term on the page <glossary term to link to>`

[s-makin]

I had to explicitly reference the glossary because on the page, the word was singular, but on the glossary, it was plural.

For example: Page fallback

Glossary fallbacks

If you would like to resolve this, you can do this.

{term}`fallback <fallbacks>`

The syntax is this.

{term}`term on the page <glossary term to link to>`

I didn't realise we could do that (although I probably should have!). Thanks for clarifying that point, I'm sure that will help out others as well :)

[network-charles]

No problem

[network-charles]

Hi @s-makin, on the glossary page, the term cgi should be CGI. It's an acronym, not a word. CGI means Common Gateway Interface.

[s-makin]

Hi @s-makin, on the glossary page, the term cgi should be CGI. It's an acronym, not a word. CGI means Common Gateway Interface.

Thanks @network-charles, there are probably still a good few of those left over from my initial pass at tidying it up. I expect that will be picked up by whoever wants to do the Cs, but if you'd like to in the interim, please feel welcome to take a pass at the whole list and tidy it up some more :) as far as I know, you're the only person working on the list currently.

[network-charles]

Nice, I fixed the CGI. I skimmed through the list and couldn't find another issue, since it is a long list, I will leave it up to other contributors to have a better look.