Glossarium: Explore Simple Text-Based Glossaries

Glossarium -- Updated 19 July 2020

Glossarium is a single macro using local variables to access multiple data files or glossaries formatted as simple text files.


From a popup list, you can 1) view individual entries from a popup menu, 2) perform a full-text search on the glossary, 3) list entries by category and 4) add new entries to a glossary, all using Glossarium.


One action in green at the top of the macro tells Glossarium how to interpret your data files. It has the following format:

	Glossary: [The name of one data file]
	File: [The full path to that data file]
	Categories: [The name of each category in the file]
	[blank line]

The name of a data file about photography name might, for example, be:


The full path looks to its data file might be:


Listing categories with a comma after each one also requires indicating the single character code for each category that is used in the glossary file. So the photography data file might have these categories:

G/eneral, C/amera, F/ilm, P/rinting, S/canning, Color T/heory


Because the data file is merely a text file, you can certainly edit it in any text editor. But it's easy to make formatting mistakes when making new entries so we've included a function to Add an Entry in the popup list.

The glossary format itself is straightforward:

	[Key Word or Phrase]
	[Definition in any number of paragraphs]
	[Category key codes]
	[blank line]


To keep things simple, Glossarium uses a unique single letter code for each category. If you indicate a lowercase character for a code it will be treated as an uppercase character. No space is required between codes in this field.

That's all there is to it, really.


We've included two sample glossaries to demonstrate the usefulness of Glossarium:

  • Regex.txt is a data file documenting regular expressions. It uses HTML tables to format references and groups them together using "Table: " as a precede.

  • Wines.txt is a data file documenting wine making and drinking that shows how to handle accented characters.

  • Printing.txt is a data file documenting commercial printing and bindery terms.

These data files were compiled from multiple online sources in a matter of minutes.


19 July 2020 -- Version 1.2a

  • Added clipboard save of current definition, deleted when window is closed

14 July 2020 -- Version 1.1a

  • Refined CSS with larger font sizes, leading, buttons

  • Add an Entry cycles until Exited

  • GlossariumSearchKey replaces LocalKey to facilitate utf8 keys (Local variables with diacriticals can't be passed to a shell script as an environment variable). The osascript requires newline be stripped.

  • LocalGlossary, which contained the glossary entries, has been replaced by a Perl variable to avoid bumping into Keyboard Maestro's environment variable limit.


Older Versions


This is not working for me.
When I click OK, I get this error:

If I choose "Categories", it opens the window, but clicking on any category does nothing.

Also, it would be appreciated if

  • you would open the app window in the user's Active Screen.
  • You could increase the font size, or give the user a setting to do so. Text is too small for me to read comfortably.
  • Rather than just throwing an error if the source file is not found, prompt the user to select it and then set the path to a KM Global Variable for future use.

Taking these one at a time:

  1. Sources. As the documentation indicates, the default 'Glossary' option in the popup links to an entry in the data file called 'Sources.' Both the data files have such an entry. Here's what the Wine data file reveals:


  1. Categories. The listing provides links between categories (in blue) but not from terms to their definitions (I don't see a way for Keyboard Maestro to link to a separate HTML prompt).

  2. Extras. a) The windows open on the Main screen on my two systems. b) You can adjust font size in each of the HTML prompts' CCS (although because that's minimized, it won't be easy). I don't see an elegant way to use a variable in the CSS with Keyboard Maestro, so maybe we just need a High Res version for big screens. Tell me what size works for your screen and its res and I'll go through the prompts for an HR version. c) The location of the source file is critical not just to the reports but to adding entries, so if you don't have that right, it's dangerous and will be dangerous every time you launch the macro.

From the Sources problem and Categories screen shot you provided, it doesn't appear you installed the data files where the macro can find them (the green action).

Hope that helps resolve the problems you've encountered.

Sorry, that's not correct.
I have verified the file locations.
Plus, the initial popup is correctly populated:


and then


which occurs AFTER you have read the file:

Using the KM Debugger and tracing the flow of your macro, here is where the error occurs:


ALL well past reading the file.
Apparently there is a bug in defining the KM Var "LocalDef".


This is exactly the issue.
This shell script is returning an empty string:

Located here:


The popup menu in the second (main) screen shows that the file has not been read into the variable that populates the popup. You have only the top four items and not the terms from the file under the line.

LocalGlossary would appear to be empty. That's created with that purple action under your black option with a Keyboard Maestro Read File action.

All of this is happening well before LocalDef is used.

So the question is: why isn't wine.txt being read into LocalGlossary?

One obscure thing to check is in the green action where the glossaries are defined. The format requires the entirely blank line that delimits glossaries at the bottom, too.

That's NOT the issue. I used your Action and just changed the paths.

I've given you all of the debug help I have time for. It's up to you now.

Yes, that's exactly what you do to configure it. Sorry for the frustration and thanks for trying it.

From here I can't tell you why wine.txt being read into LocalGlossary. Or if regex.txt is.

I have seven glossaries (including those two) in use here for over two months using Glossarium. Failure to load the variable here has been because Keyboard Maestro couldn't find or open the file.

But again, sorry for your trouble.

I have confirmed the KM IS loading the file by replacing the KM variable with the literal path selected using the Get Path (Folder) button. It DOES read the file. this proves it:


To solve this you may need to install the KM forum download zip on another Mac where the macro does not exist.

Good, that's progress. The next question is what has become of LocalMenu. That's populated from the data in the glossary file and shows up in the popup below the line:

Screen Shot 2020-07-06 at 9.52.56 PM

That image was taken from the distribution version in the ZIP file with the same glossaries. Here's what the Categories list looks like:


In short, I can't duplicate the problem here with exactly the same macro and data files.

Did you see the same issue with regex.txt?

If you were paying attention from the very beginning you would have noted the issue is with the regex.txt file:

I'm sorry you don't feel I was "paying attention from the very beginning." I was. I simply didn't notice the "ex" from "Regex" under the popup menu.

I suggest you see what happened to LocalMenu if you want to pursue this. As I said, I can't duplicate your problem on either of my systems here running the same code on the same data.

Sorry about that, too.

[For anyone reading along, the macro was adapted from the Glossary code running at Photo Corners (see the top of the left column) for some time now. I wanted a local variant for quick reference to other subjects and this fits the bill nicely.]

FYI, I've gone through the HTML prompts in Glossarium to increase the font size in the body tag about 10 percent in addition to some smaller changes in the CSS (like larger buttons). No code changes.

Gonna see if I can live with that a day or two before uploading.

I'm thinking of adding a printing terms glossary to the next distribution as well. And breaking the PDF documentation out as its own download. The Help button tells you everything you need to know, anyway.

If there's anything else you'd like while I'm getting used to the larger font size, let me know and I'll see if I can include it with the next version.

I have a few other glossaries I'm not sure would be of general interest but I'll mention them in case anyone feels like voting: ukelele, skateboarding, photography.

The blank menu listing (no search terms under the bar) for a glossary seems to be related to Keyboard Maestro's limit of 100K for environment variables.

Glossarium does read the glossary file data into a local variable that is passed to a shell script. And it is that KMVAR environment variable that appears to cause, in some cases (depending on the glossary file size and your own environment), Keyboard Maestro to omit the variable.

I'll work around this Keyboard Maestro limitation in the next version.

Why not make the CSS a KM Variable? That way each user can set their own font and size.

There are eight variants of the CSS to accommodate several layouts. So font size itself is just one component of the design.

Here's a sample of the larger size:


You can set just the font size, or even the base styling in just one CSS, and then other CSSs can add-to or change the base. In this way you could have ONE CSS to set the font-family and font-size from the User "preferences".

I have the new version up and running. Pretty tricky. But the new version avoids the environment variable limit and supports diacriticals like the original version.

Meanwhile, I don't know how a Keyboard Maestro variable would be used in CSS appearing in a Custom HTML Prompt. I know the prompt supports Keyboard Maestro variables using in a form but otherwise I believe you have to use JavaScript to display them on a page.

I also don't know how one prompt's CSS might be a base for another's.

Just not grasping what you're talking about, if you care to expand on the topic.