Glossary Best Practices

Question

I’m just starting to really set up a Glossary in our project, and I’m into a lot of questions. I’m wondering if anyone has ever written up a “best practices” document or hints on how they got things to work correctly. I’ve read the USFM markup document and the PT helps, but they don’t answer lots of questions.

For example, in long glossaries do people use chapter numbers to break it into more simple divisions? PT has 998 chapters, but when I went through my glossary and added chapters at the beginning of each new alphabetic letter, the Biblical Terms tool to add new glossary terms quit working, saying that certain chapters weren’t in the right order or were missing.

If you hand-add new glossary items, how does the Biblical Term tool add new glossary items alphabetically? Will it rearrange your hand edits to put them in order?

I’m sure the longer I work with this, the more questions I will have and I wonder if I’m missing some good resource that will answer all them.

Answer 1

If you go to https://vimeo.com/channels/paratext you will find two videos on Glossary entries. I’m not sure that all the best practices have been specified, but here are some thoughts.

1. Some folks do use chapter numbers for a large glossary, but be aware that these will need to be removed for publishing. AND this may cause the linkage to the Biblical Terms to fail. I’d recommend not using chapter numbers.
2. For print publication you are allowed 20 pages of glossary (if it is a Wycliffe publication) so building a huge glossary could be a problem at print time. Keep in mind what is permitted. Obviously for other uses (non-print) you can make the glossary as big as you want.
3. The Biblical Terms tool will alphabetize the glossary according to the order of the language settings - so keep this in mind as you work.
4. If you have an entry in the glossary you can link this to a word in the Biblical Terms tool - see video part 2.

Comments

I can’t speak for other publishing paths, but Publishing Assistant 5.1 no longer requires removing chapter numbers from glossaries before publishing.

PADev.

---

Good to know since large books in the peripherals really slow down Paratext. (I have glossaries that were created independently from the biblical Terms tool, so I do not worry about the linkages.)

Does PA ignore chapter numbers in peripheral books? Would you recommend adding chapter labels (\cl) to each chapter?

---

In general, PA does not ignore chapter numbers in peripherals; right now it’s just in the glossary. PA doesn’t ignore \cl, so if they are added they need to be removed before publication.

PADev.

---

Let me share a problem which arose in a project. They had many notes in the glossary, which had no chapters. The notes files became so big that this meant that send and receive became impossible, over fairly poor broadband. The reason for this is that each note is attached to ALL the text in the glossary (since glossaries have no chapters and verses to limit what text the note is attached to, as is normally the case in Scripture text). So do watch out for this. Probably best not to write many notes in the glossary, but to export the text to a Word file, and comment on the text there.

---

Is it possible to use chapter numbers in peripheral books and then remove them via initialChanges.txt, so that PA never knows about these chapter partitions?

---

Yes, a large glossary really slows down Paratext, even to the extent that it is almost impossible to do any editing in it. After typing a few words, it will just freeze up and you have to wait for quite a while for it to become responsive again. I only have 8GB of RAM, but when checking the memory usage, it still shows that around 50% of it is free.

For me, dividing the glossary into chapters is not an option either, as all the notes I have in it will then be moved to the beginning of the book.

Any solutions to solve this problem?

---

I have 32gb of memory and also was experiencing slowdown to the point of the glossary being completely unusable.

The notes problem also affected us. In the end the slowdown problem was so severe that I ended up moving the notes. It took quite a bit of time, but was worth it in the end.

I think I just looked at the open flags and copy/pasted the important information into new flags. This lost some of the history and discussion of team members, but I summarized that when I made new flags.

Another, much more difficult, option would be to edit the underlying Notes files with a text editor changing the chapter numbers. If you have multiple members in the project you’d want to make sure no one is making notes while you do this. And when the notes get moved to the new chapter they may or may not attach in the correct location. So you might need to find them at the top of the chapter and reattach them later on. The advantage is that you would be seeing the original notes–not summaries you wrote yourself.

Answer 2

I have a ‘best practice’ to share. Be aware of how you use of the \k keyword marker in the Glossary.

Do not use more than one \k per glossary entry.

We had initially used more than one \k per entry, which we inherited from our front translation, which seemed to work fine in 7.5. But in PT8 it caused big headaches. For example, in an entry about Passover, we might also have additional information about other feasts or related keyterms. So these sub-entries were marked with \k. But Paratext saw these as new glossary entries, and because the glossary automatically sorts the glossary alphabetically, the information was re-alphabetized in a way that make it very difficult to figure out what had happened. Later we were told that we should use some other marker for these sub-entries, something like \bdit (bold, italics). I’m not sure if this is correct, but it did help us avoid the problems we were having.

Answer 3

Thanks to everyone for their replies.

@Stephen+Katt, I see in the USFM documentation that there’s a \pi# marker for “Sub-entries, or secondary paragraph(s) (if indentation is preferred).” Did you ever considering using that for your sub-entries? If not, was there a reason you didn’t want to use that marker?

The Vimeo files covered the same information as the built-in PT Help documents.

• Does adding glossary items via the Biblical Terms Renderings windows absolutely not work with chapter markers?
  • Does anyone know any tricks to bypass this?
  • If I were to use an external editor to change the \c markers to \s when I want to use the Rendering tool and back to \c when I want to browse the glossary, are there any potential issues anyone can foresee?
  • Like @CrazyRocky pointed out, having an extremely long glossary slows PT down considerably.
• How and when does the Glossary apply alphabetic sorting?
  • I’ve set the order in the Language Setting–>Alphabetic Characters dialogue.
    • But the Glossary it re-ordering itself to be incorrect. It’s assigning some sort of order, just not the one I defined.
  • I’ve hand created an entry in the Glossary in the wrong place, and it never moves to the correct place.
    • I’ve then attached it to a Biblical Term Renderings, and it does move to the alphabetical place.
    • So does alphabetizing only work through the BT/Renderings window?

Comments

mnjames:

I see in the USFM documentation that there’s a \pi# marker for “Sub-entries, or secondary paragraph(s) (if indentation is preferred).” Did you ever considering using that for your sub-entries? If not, was there a reason you didn’t want to use that marker?

In our case we were not looking for separate indented paragraphs. These ‘sub-keywords’ were inline with the text, so we really just wanted them to have Bold formatting like other keywords so that they would stand out. This occurred mainly because we had adapted from an existing front translation and were figuring things out as we went along. The \pi# marker could work if we decided to give these other terms their own sort of official sub-entry. But I haven’t looked into it to how that would appear to the reader.

---

I just did a quick test of having two chapters in the Glossary and was able to add new terms both from the Biblical Terms tool and directly in the Glossary.

I have on occasion added some verse numbers (which need to then be removed before publication) to allow for better searching in the Glossary.

Entries do not re-order until you actually adjust a glossary entry in the Biblical Terms tool.

Note that \pi \k…\k* will still sort the entry since the sorting takes place on the \k…\k* regardless of the marker in front of the \k. And the \pi will get changed to \pi nl \p so that the entry starts with a \p.

I also have noticed that if I use some other marker for an entry (like \li or \q1), when the Biblical Terms tool edits that entry or links to that entry entry, it gets changed to \p. So, my recommendation would be to leave them as \p and then change them when the glossary is complete if needed.

If you want to have sub-entries, one option would be to use something like \pi \bdit…\bdit* so that the entry is formatted correctly, but does not get reordered.

The glossary can have lots of forms. I would recommend not spending lots of time on formatting until the basic information is in place.

---

I like your questions re the sorting how and when. Did you receive any answers? Have you done tests already and found out more?

I am getting lost in a growing glossary (a team has a focus on that at the moment for practical reasons) and am considering to try adding chapters or even verses. The more I understand how the glossary works the less data I will destroy…

Answer 4

I want to affirm anon848905’s suggestion to watch the two videos on Glossaries. While the discussion of USFM’s is very basic, they do cover some lesser known Glossary features. Two that come to mind are dealing with words that have many affixes, and re-establishing the link between the Biblical terms tool and the Glossary after it has been broken by something such as a spelling change in the Text.

I would also encourage you to read Katie Barnwell’s short article on making glossaries that is available in Translator’s Workplace. She has good advice about deciding what should and shouldn’t go into a glossary. I have started expanding on her work and mixed in the Paratext side of glossaries, but I have not completed that project. In fact, if anyone knows of other articles or materials on the lexicography side of Bible glossaries, I would appreciate hearing about them.

Answer 5

How do people break up their glossary to make it easier to read and find things? Do you use \s markers to announce each new letter? Like \s A, \s B, \s C, etc.

If so, how does that work with the automatic alphabetizing? I’m wondering because a bunch of my \s markers changed order at some point when alphabetizing got applied.

Comments

My understanding is that it is best to add the section headings right before printing. They do interfere with the alphabetization of new entries.

---

I work with a project where portions (say one Biblical book at a time) are being published as reading apps. So while we discuss best practices, we should hopefully find workflows which do not require a lot of manual tweaking for the publication of each book (assuming that we can filter the glossary and always have a relevant glossary with each reading-app).

If there can be a way to have permanent section headings or chapters and also stable alphabetization of new entries that would be a helpful improvement.

Answer 6

A good glossary is the key to to understanding scripture for many first-time isolated readers.
Thank you all. I am delighted about this thread, fulll of “me too” concerns and already full of good input.

I had planned to write up some questions about how-to and possibly some feature requests, but this has happened a few days too early.

Dear all, these questions about structuring the glossary are indeed very important. Why?

Please consider all those not-public projects, who rarely have spokespeople in a forum. A typical modern reader might be from another religion. He or she might have found a scripture app on the Play Store and is reading for the first time ever, as an enquirer.

So we need a complete and user-friendly glossary:

• we need clickable links from the main-text to the most relevant glossary entry

• we need an option to refer from one glossary-entry to another, also by clickable links

PT8 has already great tools and solid structures, namely chapters, verses and cross-references. But the glossary is not properly using these and some other users have tried hacks with chapters and verses.

I myself have tried making chapters and got error messages: chapters can only have digits and numbers. Why? If you lift this limit (please), then we could use the most solid structure “chapter” and assign those to the letters of our alphabet. There is a great danger: If you allow this idea, then other users might call LUK chapter “5”, LUK chapter “five”. This would be very bad. I do not why, but probably bad, it might break the navigation tools. So there would arise a need for yet another checking tool about “illegal chapter numbers in all non-glossary books”.

Why do we need urgently to link between glossary entries:

Our grammar has got the class-markers for our nouns in word-initial position. So singular and plural of one entry are very far from another: S_priest is not next to P_priest.

We write our glossary so that each “word which needs explaining” the most typical rendering in the text is the key-term for our glossary. So for example “pharisees” is most often met by a reader in the plural, so our description is listed under “P_pharisee”. But some readers might manually go to “S_pharisee” and then we need a link. Because our class-system is so rich, that even a native speaker cannot tell from a singular, how the plural is being formed, there are several options. So far I am just writing a special arrow-symbol and the other glossary term I want to refer to, and the user has to navigate himself to find the main entry.

So chapters (for each letter or even combination of letters) would be very helpful. And each glossary entry could have the status of a verse. So that cross-referencing and linking becomes possible. Hacking PT8 never feels entirely safe. So I beg the developpers to consider this and officially make it happen.

Our glossary is getting big. A limit of 20 printed pages does not apply to our reading apps. We also need help to navigate our glossary for our normal work, just scrolling up and down is taking for ever. Another reason to use the existing structures of chapters and verses, because for those, we have stable navigation tools on top of each PT8 window, and some users know their keyboard-shortcuts too.

Another feature we need is a way to do the follow-up of the work on each glossary item. I think you call this project-progress. Please consider our way of working:

We do not sit down on certain days and say “let us make all the glossary entries for the letter K.” We rather translate the main text and after each chapter, while we still have our studies and notes readily available, we select all those words which caused problems for translation and/or for checking and reading with other people. And then we write those glossary entries. Since it is early days, we typically have five to ten entries per chapter of text, and it is slowly getting less, as we can more often say “we have done that one already”.

So glossary entries should have something like virtual batch-numbers or virtual-admin-chapters for the purpose of applying the project-progress and checking-tools. Since we do not write them in alphabetical order, and new entries constantly keep being added, there is nothing at the moment to keep track. If nothing comes up soon, I will need to create yet another private marker and invent a status-line, based on our proven “stages” and “tasks” from the project-progress tools, but applied to individual glossary-entries.

Glossary is not Scripture but is a very important key for any new reader which allows to access and understand the main text. You would be surprised, how many “basic” terms are unknown in our part of the world. So we want to create the same level of quality and apply the existing tools of quality-control and follow-up.

Please rejoice over this feedback: My team colleague came back very glad last-week from a session of crafting glossary-entries. The local translator had to work hard and get POSS_head around several new concepts. But in the end PRO said something like “this is so amazing, we are learning so much and things make even more sense now”. Funny enough (or sadly) this work session was after the chapter of main text was already translated, so all the terms and concepts should have been explained before. Seems the glossary-work is turning into a mini bible-school for our entire team.

I would guess that - if we look at the existing structures rather than inventing a separate system - most of the work for a more functional glossary is already done. It might be as simple as allowing chapters and verses to be alpha-numeric rather than numeric-only (and checking for unwanted side effects of course). We are willing to help as testers, because this is important.

Thank you for all the ideas and the processing in this thread, will watch this with eagerness.

Comments

Tim,

If you read Kathie Barnwel’s paper on glossaries, you will see that she describes a process more like you describe. She says teams should always be looking to see what terms should be in the glossary and keeping track of them and revising the glossary and its entries constantly as feedback is received from community testing or consultant visits. It is not at all unusually for a teams understanding of a term to change or deepen over time. Teams should be looking to update their glossaries as their understanding deepens and becomes more nuanced.

Many translation tasks should be checked and a revised periodically, not just glossaries. The Project Plan Feature tends to be very linear, but cyclical tasks can be placed in the plan using careful wording such as draft, revision 1, revision 2 and so on. If it is important to you to manage the different steps in making a glossary, then you could add several explicit steps to your plan. For example in the Drafting stage have a task “identify and mark words that may need a glossary entry”. In the description field you could give more detailed instructions like “mark the headwords in the text with the markers \w…\w* or create a glossary entry from the Bible terms tool, but do not draft a definition.”

In the the Team Checking stage you could add a task like “team reviews the terms marked for the glossary” and in the description say “team accepts or rejects terms marked by the drafter for the glossary and may add terms that were missed by the drafter.”

You could then have a separate task for drafting the glossary entries, then another one to review and revise them sometime later. I hope you are getting the idea. If you want more detail about glossaries in your project plan then you should add them to your plan, and the plan will help you not miss a step.

You are correct that there are no automated checks like there is in parallel passage tool or the glosses for the interlinearizer. If this is important to you then you could make a feature request for a status check box like the parallel passages tool has. Once the team thinks the parallel passages being evaluated are appropriately parallel then a team member checks the little box saying that the work is done. Similarly, it requires the judgement of a speaker of a language to say if a glossary entry is finished or not, so a pass/fail check box is the only system that I can think of that could be used in this case.

---

anon044949:

In the the Team Checking stage you could add a task like “team reviews the terms marked for the glossary” and in the description say “team accepts or rejects terms marked by the drafter for the glossary and may add terms that were missed by the drafter.”

You could then have a separate task for drafting the glossary entries, then another one to review and revise them sometime later. I hope you are getting the idea. If you want more detail about glossaries in your project plan then you should add them to your plan, and the plan will help you not miss a step.

Jess, thank you for your input into this.

Except that what you describe for the Project Plan does not yet work in PT8 (or I am missing something). The Project Plan is structured by chapters. And our glossary entries do not have anything (like a status-tag) where we could “assign” them to a specific chapter. We could say something like “mustard-seed was first encountered and then written up in the context of LUK 15”. But when working down our Project Plan, there is no way to even bring up all those glossary entries, which “belong” to a certain chapter.

In contrast in the Biblical Terms window, I can easily bring up all Greek terms for a certain verse, or chapter or book etc. So we agree with you, but we are missing the tools. Or rather it seems that this thread is turning into a collection of ideas - which might later transmogrify into a multi-user feature request. Too early yet, I am still collecting ideas and seeing what other users are doing. Thanks again.

Answer 7

In another thread, the topic of using Paratext and Fieldworks together came up. I would like to see a glossary making tool in the future where the user would be able to tag entries in the Fieldworks database that would be imported into the Paratext Glossary. It could be dynamic, so as the data for those words is refined in Fieldworks the glossary entries would be updated. Fieldworks already allows you to take subsets of your data for making different dictionaries; why not have a category “Bible Glossary” and link that category to Paratext. Fieldworks is a very good dictionary making program, we should use that power to make better glossaries instead of duplicating all of those functions in Paratext.

Answer 8

It is national holiday here, so we have a quiet day in the office and can do some research and development:

We created a custom marker and tested how we can track the progress-status of each glossary entry, using our internal codes from our Project Plan.

Later, we want to try the idea of assigning virtual chapters or batch-number to our glossary-entries, for progress tracking.

Sadly, the blue “progress” icon does not show up while working in our glossary. And even worse, when trying to bring up the window (to look up a code), I just got this rather harsh message:

Current book (GLO) is not in the project plan.Since it is not a Scripture book, it cannot be added to the progress plan.

So for the last few days we have discussed here how best to work on the Glossary and now PT8 is telling me that we cannot even do quality control and progress tracking. Not a bug of course, but please re-consider.

I know of projects where the consultant is checking the glossary (not like Scripture, but similar) before publishing, because it goes out in the same book and has a major impact (for better or worse) on the readers’ understanding of the main text. So why block progress- and quality-tracking at a technical level? Please reconsider dear people who make the policies.

Comments

Tim:

So why block progress- and quality-tracking at a technical level? Please reconsider dear people who make the policies.

Just so you know the reasoning behind this decision:
The glossary, extra books, etc. usually have a different (sometimes vastly different) set of steps to go through than the Scripture books. Because the Assignments and Progress only allows specifying a plan for the whole project (i.e. things you do for every book), for you to be able to add in the different steps for the non-Scripture books, it would clutter the rest of the steps for the Scripture books and you would likely be forced to check off things in books that would never be done.

I think there is a feature request to allow specifying the plan per-book so that checking non-Scripture books would be possible without being annoying. However, this has not become a high-priority yet.

---

Thank you @anon291708 for giving reasons and background. I agree that the glossary needs different steps of checking.

I was only shocked that PT8 does not allow any kind of checking through the Project Plan, it even refuses to open the checking window (so we cannot even look up our references for doing our manual status tracking, while we have the cursor inside the glossary “book”.)

The Project Plan tool is powerful and we could easily spend some time and write a custom stage with the needed custom tasks. But since the tool is all locked up, we cannot use it at all.

The progress tool is all new. And we like it a lot for normal books: We keep track on paper for all tasks which cover less than an entire chapter. And then we tick the boxes in PT, once an entire chapter is done. (This office has mostly free lancers who come in when they find time.) So we use a numbering system of references to easily know on paper which task is which.

So when I give you feedback, please keep in mind that we like it and appreciate it. Still it could serve more purpose with less locking-up - depending what other users confirm or declare irrelevant for other projects.

I remember that in the old PT7 we had only three or four tasks defined in Project Progress and I found that we could customize it to have a maximum of 8 tasks. But we never managed to squeeze the reporting of all our local tasks into just 8 steps, so reporting was a mess. Again: we appreciate the new tool, it has got all this potential, that is why we want to make it fit our reality better.

When we migrated to PT8 and had our first look at the Project Plan tool, we liked the completeness and we got nervous about the rigidity of the concept and the proposed example-plans. Like you say “only allows specifying a plan for the whole project”. So we spent almost one hour un-clicking all those “can only start this task nnnn after task mmmm has been completed”. Because that was totally unreal for our local situations and team and way we need to allow for sicknesses, absences, power cuts, whatevers. The project where I have my hands in the PT, is not a perfect project and we rather report and record the ugly truth than be forced by a perfect plan to not-report because some box was “locked up”.

I have not forgotten that this thread is about the glossary. So a first request would be to please unlock the reporting tool, so that at least the window can be opened from the glossary-book (for looking). Even more helpful would be to let users write custom stages and tasks for what you are calling extra books, until a more wonderful idea might be realized. We are working on the glossary every week as we go along the main translation. And since new glossary entries keep being pushed at different places, according to the alphabet, we need some smart custom ways to keep track of our glossary-tasks.

I have created prototypes of a status-line for each glossary entry yesterday. Using the same local reference numbers as for our normal text work (spell checking, several rounds of proof reading, certain checks, etc). And some tasks that would not make sense (like assigning Greek terms to each word in a glossary explanation) we just skip.

Next I want to experiment with virtual chapters or batch-numbers to keep track of sets of glossary entries which get worked together in one working-day. So please keep us posted about the official PT road-map, so that when the “real tools” for tracking extra books are ready, we can migrate there.

Answer 9

Testimony: I have converted one Glossary from “no structure” to “33 chapters”, for a language with 33 characters in its alphabet. Some of those characters can never appear word-initially, so those chapters will remain empty.

PT8 seems to work very well with this new setup. New glossary entries - as created from the Key Terms window - still get sorted precisely where they need to be alphabetically. Have not observed any bad side-effects and team has not complained so far.

This is one more sad example where the human has to adapt to his/her computer-tool; PT8 does not accept anything but pure numeric-digits after \c - so I made an alphabet-chart for the team to quickly look up glossary entries: You want a term starting with “sh”?: Go to chapter 28. Still this is much better than the old many-screens-long unstructured glossary.

Thanks to @anon848905 who - I believe - first shared about making dummy “chapters” in this thread.

Answer 10

@anon716631 @mnjames

Have you submitted Feedback to Paratext about this slowness issue? Perhaps when you do that you could detail your need for changes to how the Glossary (and Project Notes in the Glossary) function.

Comments

I had assumed this problem was already known to the developers, but I’ve now sent in a bug report.