xref for terms

[Oscar Levin]

At drop-in yesterday Chrissy and I were chatting about her colleagues work on converting a chemistry textbook to PreTeXt, and one of the things he had in the original word versions was definitions of terms in footnotes on the term being defined.  We agreed that a good way to do a similar thing in PreTeXt would be to wrap the word being defined in an #xref to a definition (either earlier in the text or in the backmatter), and wrap that in a #term.  So:

```

<term><xref ref="def-graph" text="custom">graph</xref></term>

```

Similar to a feature David F once showed off that let you click on a defined word and see its definition, I think this would be great to help remind readers what these things mean later in the text.  

But what do we think about simplifying the markup to be just 

```

<term ref="def-graph">graph</graph>

```

which could be preprocessed into the longer version (or be handled separately, I suppose)?

[Alex Jordan]

Is #term being used here in a sentence, or is it the #title of a #definition? Or something else?

--
You received this message because you are subscribed to the Google Groups "PreTeXt development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/a134dc7b-9be6-48a0-aee1-d13485f939edn%40googlegroups.com.

[Oscar Levin]

I'm thinking the existing #term tag, used inside a #p.

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/CA%2BR-jrduoPmPVz-NF6tUR0HbM0V%2BbPzjOFjNutcCdhn3rVGD7A%40mail.gmail.com.

[David W. Farmer]

A new possible attribute on a term seems like a natural way
to do this.

The earlier feature Oscar mentioned would automatically make a
knowl on every instance of a defined term. One of the issues
was that the same word (or phrase) can mean more than one thing.
Occasionally it is because the same word, isomorphic for example,
may be defined in more than one place in the document. More
often, the word has a common meaning, and is being used that
way instead of as terminology.

Would it be helpful to have a script which put these term
tags everywhere, and then the author can edit as needed?

Another issue is that it is distracting to see knowl markup
all over the place. I handled this with "stealth knowls",
which would look like regular text until you hovered over
it. This had accessibility issues because you have markup
around the word(s), and that is visible to a screenreader.
Maybe something more subtle, but always visible, would be
better than the usual knowl appearance?

You can see it here, where "group", "subgroup", and "ring"
are stealth knowls:

https://sl2x.aimath.org/book/aafmt/section20-2.html

Regards,

David

> https://groups.google.com/d/msgid/pretext-dev/CAOU9BaUfuyKF4hNHdm7EQKsTjvqOdr8Yme5h-zswnY-qDf77MQ%40mail.gmail.com.
>
>

[Rob Beezer]

I think that all sounds real good. And given the intricacies of #xref, a
pre-processor conversion, as you suggest, would be great. (My mind had already
gone there during the paragraph prior to your suggestion!)

Are you interested in doing a PR? A complete one - broad testing (EPUB, too),
full documentation (sample article, Guide)? Soup to nuts? My only suggestion
would be to use the "repair" pass in xsl/pretext-assembly.xsl, despite its name
now becoming a bit inaccurate.

Thanks,
Rob

> --
> You received this message because you are subscribed to the Google Groups
> "PreTeXt development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email

> to pretext-dev...@googlegroups.com <mailto:pretext-
> dev+uns...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/

> a134dc7b-9be6-48a0-aee1-d13485f939edn%40googlegroups.com <https://
> groups.google.com/d/msgid/pretext-dev/a134dc7b-9be6-48a0-aee1-
> d13485f939edn%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Rob Beezer]

Thanks for the history, David, I'd forgotten some of the finer details.

On 11/22/25 10:45, David W. Farmer wrote:
> Would it be helpful to have a script which put these term
> tags everywhere, and then the author can edit as needed?

With my author hat on: maybe? Certainly on existing mature material, it might
be a great way to start - you can just not accept certain changes as part of a
commit. If you are actively making new mateial, maybe it would be a fiddle to
get the same false positives over and over? What do other authors think?

> Another issue is that it is distracting to see knowl markup
> all over the place.  I handled this with "stealth knowls",
> which would look like regular text until you hovered over
> it.  This had accessibility issues because you have markup
> around the word(s), and that is visible to a screenreader.
> Maybe something more subtle, but always visible, would be
> better than the usual knowl appearance?

I've recently been using a certain device more and more in the pre-processor.
When something gets permuted by the pre-processor as a convenience, it picks up
an attribute that records that the author's source was different than the source
seen by the conversions. Here, the #xref coming out of the pre-processor might
have a

@authored-on-term

attribute on it. Then the #xref code in the HTML conversion could make
adjustments to be stealth-y.

Rob

[Jeremy Sylvestre]

On Sat, 22 Nov 2025 at 09:48, Oscar Levin <oscar...@gmail.com> wrote:

<term><xref ref="def-graph" text="custom">graph</xref></term>

I do this a lot in my linear algebra book, but usually do

 <term><xref ref="some-def" text="title"/></term>

I only use text="custom" if I need to change the defined term to plural or some other slight modification like that to make it fit into the sentence.

Would that be the default @text setting for the implied xref in the new markup, if no text has been provided as content inside the term tag?

[Jeremy Sylvestre]

On Sat, 22 Nov 2025 at 11:45, David W. Farmer <far...@aimath.org> wrote:

Another issue is that it is distracting to see knowl markup
all over the place.  

The <term> is already getting styled as bold-italic. Does a dashed underline create that much more of a distraction?

Or if it's a <term> with @ref, you suggest it gets styled differently than a <term> with no @ref ?

[Alex Jordan]

> I only use text="custom" if I need to change the defined term to plural or some other slight modification like that to make it fit into the sentence.

I feel like I'd be doing this most places, to change the capital letter in the title to lowercase when used in a sentence.

--

You received this message because you are subscribed to the Google Groups "PreTeXt development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/CALMYOnd-WbeuRQhbU38qhTL2d0rt98ppY1%2Bt%2BJ0YXZOXrdOPAQ%40mail.gmail.com.

[Jeremy Sylvestre]

On Sat, 22 Nov 2025 at 13:51, Alex Jordan <jordanc...@gmail.com> wrote:

> I only use text="custom" if I need to change the defined term to plural or some other slight modification like that to make it fit into the sentence.

I feel like I'd be doing this most places, to change the capital letter in the title to lowercase when used in a sentence.

Sure. I'm suggesting

<term ref="whatever">word</term>

gets turned into

<term><xref ref="whatever" text="custom">word</xref></term>

by the preprocessor, but 

<term ref="whatever" />

gets turned into

<term><xref ref="whatever" text="title"/></term>.

Best of both worlds.

I don't have the capital letter problem because my book is not the typical linear-exposition format. I put all my definitions for each chapter in a <dl> in its own section (basically a DIY glossary), and just like in an index I don't capitalize the terms.

[David W. Farmer]

Currently I see "term" as indicating "here is the place where we
are defining this word". So, a new use of term with an attribute to
make it a reference to the definition, would not be styled as
term currently is.

Separate issue: how can this new feature work if a term is
originally defined in a paragraph? So, there is not xml:id to
refer to.

[Oscar Levin]

I wasn't thinking these would be styled differently, but they could be.  Using a standard style for the knowl seems reasonable.

I would assume this would require an xref-able definition.  Perhaps in a back matter glossary.

--
You received this message because you are subscribed to the Google Groups "PreTeXt development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/666bcc9d-6a68-db79-554-b092d58de3df%40aimath.org.

[Rob Beezer]

A couple of comments, one technical, one more philosophical.

1. A #term with an @ref could have an optional @text which just passes
through to the manufactured #xref. I think a default of "custom" does make the
most sense.

2. While writing FCLA, I realized that #notation and #term made the most
sense to me inside #definition. So at some point that became a rule for
author-me. To David F's remarks, I think there are

A. casual definitions. A #term in a #p. Tom J does this consistently in AATA.

B. formal definitions. A #term first occurs in a #definition. If we enforced
this (not a proposal), then having a guranteed #definition as an ancestor can
make certain things automatic.

C. #term that just point out that a word is a term, though maybe not its first
use. Sorta like David's stealth knowls.

<aside>
When writing FCLA I decided that any defined term should be a noun. For example
I did not define the action (verb) "to row-reduce". Theorems would say things
like "Suppose B is a matrix in RREF that is row-equivalent to A. Then if B has
property X, then A has property Y." Cumbersome? Yes, but I think logiclly it
helps. If you "row-reduce" A is it still the matrix A?
</aside>

Rob

On 11/22/25 13:41, Oscar Levin wrote:
> I wasn't thinking these would be styled differently, but they could be.  Using a
> standard style for the knowl seems reasonable.
>
> I would assume this would require an xref-able definition.  Perhaps in a back
> matter glossary.
>
> On Sat, Nov 22, 2025, 2:17 PM David W. Farmer <far...@aimath.org
> <mailto:far...@aimath.org>> wrote:
>
>
> Currently I see "term" as indicating "here is the place where we
> are defining this word".  So, a new use of term with an attribute to
> make it a reference to the definition, would not be styled as
> term currently is.
>
> Separate issue:  how can this new feature work if a term is
> originally defined in a paragraph?  So, there is not xml:id to
> refer to.
>
> --
> You received this message because you are subscribed to the Google Groups
> "PreTeXt development" group.
> To unsubscribe from this group and stop receiving emails from it, send an

> email to pretext-dev...@googlegroups.com <mailto:pretext-
> dev%2Bunsu...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/pretext-

> dev/666bcc9d-6a68-db79-554-b092d58de3df%40aimath.org <https://
> groups.google.com/d/msgid/pretext-dev/666bcc9d-6a68-db79-554-
> b092d58de3df%40aimath.org>.

>
> --
> You received this message because you are subscribed to the Google Groups
> "PreTeXt development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email

> to pretext-dev...@googlegroups.com <mailto:pretext-
> dev+uns...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/

> CAOU9BaUSqMSpLoW6k1JOTUve_jgdUsvrG6aT%3DzrSo5bZNvx%2Bgg%40mail.gmail.com
> <https://groups.google.com/d/msgid/pretext-dev/
> CAOU9BaUSqMSpLoW6k1JOTUve_jgdUsvrG6aT%3DzrSo5bZNvx%2Bgg%40mail.gmail.com?
> utm_medium=email&utm_source=footer>.