RE: Glossary issues for discussion

Hi there,   First, thanks for sharing this discussion. Rather than add more comments inline, I summarized my input.     Preferred/primary term As for the preferred/primary form, I do think there is a primary form by context . When I help clients, I recommend that if you have multiple terms, then you identify the preferred term by context and specify the context in each topic with glossUsage.   I’m agnostic about the adjective for the primary/preferred form, but it would be good to select one.   References to alias forms References to alias forms are the most challenging aspect for using the current glossary support. From the rendered glossary perspective, the key patterns I’ve observed in English content with references to alias forms: Term and redirection to a preferred term (no definition) Term: not preferred for context Alias: preferred for context Rendering: See [preferred term] Markup: glossAlternateFor (because it has the linking capabilities) Term, definition, and reference to related term Term: preferred for context Alias: not preferred for context (but might be the preferred term in another context) Rendering: See also [term] Markup: glossAlternateFor type=”synonym” to get a link. (glossSynonym doesn’t allow a link to the other topic)   Are these the most common alias references? If so, can we recommend common usage? Is it possible to have glossSynonym allow a link?   Definition limitation Although the best practice is to have a single definition per term instance, I don’t think we should enforce this.     Symbols glossSymbol as a reference to an image doesn’t allow for cases where the representation is a special character, such as for scientific content. I’m in favor of removing it and recommending that folks use glossProperty because it can be a special character or be a reference to an image (using @href and @type).     Have a great day, Amber     From: [email protected] <[email protected]> On Behalf Of Scott Hudson Sent: Monday, November 6, 2023 8:40 AM To: Dawn Stevens <[email protected]>; dita <[email protected]> Subject: [dita] Re: Glossary issues for discussion   Hi Dawn, et al, I’ll include my answers inline [SH]   From: [email protected] < [email protected] > on behalf of Dawn Stevens < [email protected] > Date: Wednesday, November 1, 2023 at 10:49 AM To: dita < [email protected] > Subject: [dita] Glossary issues for discussion [External Email]   Hi all, I am preparing the glossary section of the technical content specification for review. After meeting with Kris, we decided that some important questions should be discussed before sending it out for review. Here are the questions that we will discuss in our next meeting:   1 – What are we defining? The term that appears in glossTerm is what? Is it just a term of any status? Is it a primary term? Is it a preferred term?       Terminology is inconsistent throughout, but seems to imply the word is either primary or preferred. Is there a distinction between these two adjectives? And do we agree that glossterms should only be primary/preferred. What about using DITA to create a glossary for translators who need to know these other terms perhaps that are not primary or preferred? Consider glossAlternateFor which is an xref to another term – there is an implication that one term is preferred over the other. The way the description is written the alternate would be less desireable than the “preferred” term in the glossterm. Furhter, the glossStatus element allows me to set a value or something like prohibited – why would I do that is the glossterm was always the preferred term? If not specified, glossStatus staets that the glossterm is preferred and an alternate would be an allowed term.   [SH] I think we need to continue to provide options for Aliases (glossAlternateFor covers this). I don’t think that glossterms should only be primary/preferred. If you provide a glossAlternateFor link from term A to term B and neither state that they are the preferred term, how should we handle it? They both can’t be the preferred term, right?   2 – Are we agreed that one glossentry topic includes only one definition – one single sense of the term. Is that too prescriptive? Couldn’t a company choose to create a dictionary that would include perhaps numbered definitions?   [SH] No. I think we should provide the option for multiple definitions. We had that use case at Jeppesen, though it’s been too long for me to recall a specific example. I do think there is a use case for multiple, numbered definitions.   3 – glossPartOfSpeech is defined by the @value attribute. However, if used, it is presumably translatable content. Should this element be modified to contain text instead? If we keep it as an attribute – why is noun the default? Does there need to be a default? glossProperty has a similar problem, but is open-ended so we don’t know how these properties might be used and whether they would be translatable.   [SH] There is a limited set of Parts of Speech, so I don’t know why we’d want to have it contain text. A prescribed list cuts down on potential errors or typos that could affect processing. glossProperty is generic, so needs to be flexible for unanticipated values. I’m sure there could be company-specific properties that would have their own custom processing to handle them.   4 –. What is the distinction between glossUsage and glossScopeNote?   [SH] IMO, glossUsage is the anticipated / expected use of the term in content. glossScopeNote describes the types or volumes of content that this term covers. I think they cover different aspects of the term that are important to keep distinct.   5 – why would you put an image in glossSymbol rather than just embedding it in the glossdef?   [SH] I think the glossSymbol is for an image associated with the term, but it is not, in itself, a definition of the term. I think it’s akin to an example of the term. Perhaps that is something  that is missing, or perhaps we could get rid of glossSymbol in favor of allowing the generic <example> element?   Looking forward to hearing your thoughts.   Dawn