Design feedback

[andrewpbray]

@coatless @mcanouil

I've been inspired by your extensions for Quarto and was wondering if you wouldn't mind trying out this filter and providing any feedback around its design.

A few things that I've been thinking about:

1. The filter is currently set up to indicate the location of the glossary using a Div with an id and then pass options through YAML. This format was inspired by similar functionality in quarto (i.e. listings). However, it seems like these options could also be passed via attributes to the same Div. What are the tradeoffs of this decision?
2. There is currently no cross-referencing functionality built into the filter, largely because my understanding is that the cross-referencing system is getting overhauled and so I figured I'd wait.
3. Once could add additional attributes to alter the appearance of each block in the glossary instead of just copying it as it appears in the original location (similar to customizing the fields that appear in a listing). My inclination is to use the extension for a bit to decide whether or not such a thing would be useful.
4. I forgo the built-in Pandoc block type of a definition because this felt a bit more general. Are there any downsides to this decision I'm not seeing?

Thank you!

[coatless]

Nice initiative for quarto!

My initial thoughts are the use of a code block syntax feels more natural compared to the carpentries' glossario project (GitHub Source) and PsyTeachR's {glossary} (GitHub Source) use of YAML. Though, I see two downsides:

• The existing glossaries would need to be ported to the new format.
• The extension is unable to handle internationalization/i18n without providing Div options of term (for linking the term across languages), word (word in translated language), and language (origin of the word) could permit, e.g.

:::{.definition lang="en" term="toad"}
A toad is another name for a frog... 
:::

:::{.definition lang="en" term="toad" word="sapo"}
Un sapo es otro nombre para una rana...
:::

On the other parts:

1. Keep extension options out of the #my-glossary Div as you allow for the Div id to be different.
2. Looking forward to seeing cross-references implemented in a post-v1.4 Quarto world, c.f. issue Epic: Crossref Overhaul quarto-dev/quarto-cli#4944
3. If a lot of customization is desired, then the underlying data structure will need to have stricter entry requirements. The required structure will be highly dependent on what use cases the glossary should support (e.g. diagrams, sound clips, self-linking, et cetera).
4. Formatting and internationalization become harder without diving into custom key/value pairings in Divs and Spans

Outside of that, a minor hiccup... If glossary.id is not set, then there is no default to fall back on as options_id is not defined initially to my-glossary.

glossary/_extensions/glossary/glossary.lua

Lines 7 to 9 in da0f734

	local options_class = "def"
	local options_contents = nil

glossary/_extensions/glossary/glossary.lua

Lines 27 to 30 in da0f734

	-- read id
	if options.id ~= nil then
	options_id = options.id[1].text
	end

So, you may wish to define:

 local options_id = "my-glossary" 

[andrewpbray]

Hearty thanks @coatless !

Thanks for the lead on Glossario; I hadn't come across that before. I can see the benefits of the YAML reference file, but I'm not sure how that'd be implemented with a single pass document filter. It's possible the new cross-ref system would give some idea of how this could be implemented.

My first quick and dirty design for making a glossary for my own use was something similar: an R script that parses the files in the project directory and creates a YAML file that's then read into using a custom listing with a new ejs template. I find "write a pre-render script in R" to be my go-to solution for lots of Quarto functionality, but it's been fun and instructive to think how to implement things using filters.

That's a good point about the need for stricter entry requirements for any data structure that would permit more flexible formatting output. I plan to use the filter to build glossaries of key terms and functions for course website and also to pull together learning objectives spread across lecture notes and assignments. Both of these use cases could feature a dependency structure ("you need to learn this before you learn that") but I'd need to way to flag those dependencies on the way in so that they can be used to format the output (say, with a graph of learning outcomes). Glossario has some interesting functionality in this regard that I'll keep in mind as I tinker around with this filter.

Thanks for your careful eye on the defaults - fixed! (#2 )

---

As an aside, reading through webr.lua, this cracked me up:

  -- This is crazy fragile since Lua lacks a directory representation (!?!?)

And also made me feel a bit less bad about the hijinks needed to translate globs into a list of files.

[coatless]

@andrewpbray I think you might be interested in the work Hadley did circa 2017 (?) with Stanford's Data Challenge Lab (DCL) on developing the curriculum dependency structure, c.f.

https://dcl-docs.github.io/curriculum/
https://github.com/dcl-docs/curriculum

[mcanouil]

@andrewpbray Sorry for not getting back sooner. I unfortunately do not have much time to review, but @coatless did a fine job ;)