Add What is a Glossary? explanation

[bruce-esrig]

Draft of a new explanation What is a Glossary?

This version is a progressive discussion of what meaning is conveyed in a glossary. As features are introduced, examples are provided of definitions that use those features. The examples are from the Server glossary, with rewrites that vary in their ambition.

There's a cultural judgement here. Advanced dictionary features are de-emphasized in this version because many top-of-mind dictionary features are used primarily by lovers of terms rather than those hungry for practical definitions. The philosophical discussion of features of terms from the "style guide" version (PR #184) can be re-introduced as desired.

[s-makin]

Really nice discussion here, very concise, but also informative. I've left some suggestions for your consideration :)

All of my suggestions are non-blocking, but I do think that if we were to treat the examples as glossary entries using the MyST syntax, the entire page would then become a fully functional example. Readers can then use the source code of the page in their own projects.

As an additional/final suggestion, since this is an explanation page it may also be helpful to the reader if we include links to the MyST and rST glossary overviews. These are the ones I usually refer to but there may be others:

• Myst
• rST

[s-makin]

For all these examples of glossary features, I'd recommend creating a mini glossary environment for each of them so they render on the page as they would in a full glossary. The syntax should be something like this for MyST:

:::{glossary}
Term goes here
: Term definition/gloss goes here
:::

(see the MyST docs for a full description)

[bruce-esrig]

That's really nifty!
If you'll pardon the rudimentary question ... does the Sphinx parser recognize the various markdown paradigms as it encounters them, or does it need additional cues? Before you said this, I was implicitly assuming File extension == > markup language.

[bruce-esrig]

Update:
MyST recommends relying on Conda.
https://myst-parser.readthedocs.io/en/v0.16.1/sphinx/intro.html
I have Ubuntu running on ARM (my MacBook).
However, Conda doesn't support ARM.
conda/conda#13951

Support for MyST is experimental on ARM.
Wondering whether to try the experimental path that Mara Lampert's blog mentions.
https://biapol.github.io/blog/mara_lampert/getting_started_with_miniforge_and_python/readme.html

Previous remarks:
I'm suspecting that MyST needs to be installed. Would that be added to the "Set up Sphinx" topic, or built into Makefile?
The symptom is that when I add myst_enable_extensions = [ "colon_fence" ] to conf.py, the build breaks.
Even without installing MyST, Sphinx does accept this: adding "myst_parser" to extensions in conf.py.

[s-makin]

I've just checked the conf file and it looks like MyST should just work automatically - myst parser is included as part of the canonical sphinx extension (which is enabled). Have you tried running a clean build? Sometimes it doesn't just enable an extension and you have to rebuild the whole thing from scratch. (make clean and then make install should see everything set up correctly, then make run should work).

If running a clean build doesn't work, let me know and I'll do some more digging.

[bruce-esrig]

Alas, a clean build does not suffice. I restored conf.py and ran make clean; make install; make run. The local preview of my latest revision of the glossary_what.md file shows

:term:`NFS`

rather than processing the term reference.

I put some notes in my previous comment about difficulties installing MyST on ARM.

[s-makin]

I think I found the source of the problems! I've added suggestions for all the instances I could find (I may have missed one or two though)

[bruce-esrig]

Thank you, Sally! I was a bit confused about which markdown languages work where. I now think that MyST works on top of MD (in .md files) but RST is separate (in .rst files).

[s-makin]

That's exactly right :) MyST is just an extension of standard markdown that adds a lot of the functionality you get with rST. All the Canonical GitHub projects that use Markdown will be using MyST to some extent (probably) in their .md files, otherwise they'll use rST. You can mix-and-match markdown and rST files in the same project (sphinx will allow you to work with both), but each individual file has to be one or the other.

[s-makin]

This is where I think using mini-glossaries for these examples would really shine - then you can cross-reference between them as if they really were glossary entries :)

[bruce-esrig]

I see how mini-glossaries can be helpful. I created some along the way, and then pooled a few glossary entries at the bottom in a section titled "Appendix 2". Those are the terms that are referenced but are not themselves needed as examples.

[bruce-esrig]

I also created "Appendix 1" for code examples. Instructionally, I think it's clearer to have them collected. As how-to material, it might need to be split out, but that depends on how orthodox we're being about factoring instructional information about glossaries.

[s-makin]

I think all of this can reasonably be counted as "explanation" rather than "how-to" - having illustrative examples is totally fine in an explanation page :)

[s-makin]

Hi @bruce-esrig, following our conversation on Friday I've taken a second look and I think I have found and suggested corrections for the bits that you mentioned were not rendering properly. Let me know if these solve the problems you were having, and if not I'll take another pass :) content-wise I think it's really good and almost ready to land

[s-makin]

Suggested change

	A definition is a statement of fact that conveys the meaning of a term.
	A definition, or *gloss*, is a statement of fact that conveys the meaning of a term.

[bruce-esrig]

A gloss is more than a definition since it can include all kinds of extra features (See also, etc.).

Second, I was hiding a question about terms with multiple meanings. Is the gloss everything after the entry, or is a gloss what is written about an individual numbered sense? I'm inclined to define gloss as the smaller of the two, so that each numbered sense has its own gloss.

[s-makin]

In that case, should we redefine the header "Structure" as "Structure of the gloss" or similar?

[bruce-esrig]

How about ... (putting the content here till my git fix is in) ...

Structure of a gloss

This section describes a gloss that explains a single sense of a term.

If a term has multiple senses, each sense has its own gloss. In that case, the glosses under the term are numbered. The order of the glosses should be instructive, with the most basic or common senses presented first.

[s-makin]

We probably want to also encode this example in a code block too - I suggest using the standard markdown wrappings (the triple backticks at the start and end). I can't create a note suggestion for that because GH doesn't render them properly.

[bruce-esrig]

To get the triple backticks to show up, I needed to wrap them in a different code block mechanism, so I used 4-space indentation. That's the approach in the file attached to this recent comment on this PR ... #199 (comment)

[bruce-esrig]

GitHub has quite a sense of humor. I got a great version of the file ready and now I'm having an authentication problem on "git push". (Namely: I'm part-way through configuring SSH for GitHub and may need to complete that. In the meantime, I'm getting prompted for user name and password, which is no longer supported.)

So let me try to attach the file here.
glossary_what.md

[bruce-esrig]

@s-makin OK, I think this is ready for another review. It builds locally. I set up SSL for my bruce-esrig repository on GitHub and was able to push my main file. On the server side, there are two warnings: "not in toc" and "spelling". But these don't appear when I build locally. I think I have both the applicable index.md file and the custom wordlist among the committed files, so I would think that the build would succeed on the server side. Can you see the problem?

[bruce-esrig]

@s-makin OK, I think this is ready for another review.

OK, I synced my fork and then found the issue.
The new "How to be a great peer reviewer" topic needs the following two fixes.
I have commented on CBID2's pull request #213 to let her know.

website/library/reference/index.md: add
How to be a great peer reviewer <how-to-review-someone's-work>

website/.custom_wordlist.txt: add
capitalization

[s-makin]

@s-makin OK, I think this is ready for another review.

OK, I synced my fork and then found the issue. The new "How to be a great peer reviewer" topic needs the following two fixes. I have commented on CBID2's pull request #213 to let her know.

website/library/reference/index.md: add How to be a great peer reviewer <how-to-review-someone's-work>

website/.custom_wordlist.txt: add capitalization

Good catch @bruce-esrig - I've taken the liberty of adding the reviewing page to the navigation and have added the spelling to the custom wordlist. Since the PR that adds the page was already merged, it's too late to update it and I had to do this via fresh PRs. All present and correct now.

[CBID2]

@s-makin OK, I think this is ready for another review.

OK, I synced my fork and then found the issue. The new "How to be a great peer reviewer" topic needs the following two fixes. I have commented on CBID2's pull request #213 to let her know.

website/library/reference/index.md: add How to be a great peer reviewer <how-to-review-someone's-work>

website/.custom_wordlist.txt: add capitalization

Hi @bruce-esrig! :) I tried implementing this in PR #220 but the build failed for someone odd reason. Can you help?

[s-makin]

All building correctly now - looks good in the rendered preview! I just have one final question, but other than that I'd say this is ready to merge.

[bruce-esrig]

I have a question too! What should be under Handbook vs Writing Resources? I'm thinking of this Glossary material and the new "How to review" material.

And a hiccup -- I need to detangle my git repository. (Or simply create a new one.) Following @rkratky 's rebase instruction left me with something to merge, so now I need to figure out where my HEAD is at and related questions. Graham said he would support if I reach out to him.