[DEPRECATE] Excess math elements

[Rob Beezer]

There has long been a surplus of elements for math, dating to the earliest days
of PreTeXt, when design decisions were not as well-informed.

Short version: #me, #men, #mdn have been deprecated (for a week or two now
already). No emergency action required on your part.

Long version: we now have the following.

* #m - inline, as before, no changes.

* #md - with content, "bare", unstructured, no "mrow" children. Existing
element, new capability. Just put one line's worth of LaTeX into the element.
A single equation/expression. Replacement for #me, #men.

* #md - structured with #mrow. Pretty much as before with some new twists (read
on). For multi-line display math, with alignment control. Replaces #mdn.

Aah, "what about numbering?", I hear you ask. Good question.

* The global default has always been to not number equations, it still is. But
you can now control this global document-wide default explicitly with

docinfo/numbering/@equations

set to "yes" or "no". New feature, which I think will be welcome.

* The #md element now accepts a @number attribute. It provides the old #me
v. #men behavior for one-line math. It is a convenience for a multi-line #md,
in addition to providing the old #mdn behavior. It is also an override for
the global default.

* The #mrow element has always accepted a @number attribute. It functions as
before, but is now a further override on whatever numbering behavior might be in
effect.

What do you need to do?

* Start using the new #md forms now, as you write new material.

* Right now the pre-processor is converting #me, #men, #mdn into equivalent
forms using #md. (So a lot of old, complicated code has gone away.) I do not
expect ever having to turn that off.

* In a few months, I will turn on a deprecation warning. It is going to be a
new "bulk" message. "You have 4,621 deprecated #me elements." It won't list
all 4,621 locations. You can get ahead of that now.

* If you are happy with the old document-wide default (no numbers) the
following is a recipe for bulk search-and-replace (on a branch, or with
backup!). Do these in the order given here. If your document is heavy with
numbered equations, you might find it easier/better to set the global default
and do the following a bit differently. Note: any <mermaid> elements you may
have can get caught up with fixing #me, so watch out for that.

<mdn -> <md number="yes"
</mdn> -> </md>

<men -> <md number="yes"
</men> -> </md>

<me -> <md
</me> -> </md>

TO DO:

* I think an #xref to a bare #md is working, but please report anything
amiss there.

* An #mrow can have a @tag attribute (think a "number" like (*)). It
should be possible to *add* this as a new feature to a bare #md.

Rob

[Rob Beezer]

On 11/21/25 12:21, 'Rob Beezer' via PreTeXt announcements wrote:
> *  If you are happy with the old document-wide default (no numbers) the
> following is a recipe for bulk search-and-replace (on a branch, or with
> backup!)

From Kiran Kedlaya comes the incantations to make the necessary bulk edits from
the command-line, adjusting files "in-place" with sed ("stream editor"). Again
- make backups, or work on a branch.

> sed -i 's@<mdn@<md number="yes"@g' source/*.ptx
> sed -i 's@</mdn>@</md>@g' source/*.ptx
> sed -i 's@<men@<md number="yes"@g' source/*.ptx
> sed -i 's@</men>@</md>@g' source/*.ptx
> sed -i 's@<me@<md@g' source/*.ptx
> sed -i 's@</me>@</md>@g' source/*.ptx

Rob

[Rob Beezer]

> In a few months, I will turn on a deprecation warning.

As promised, #me, #men, and #mdn will now raise deprecation messages. But only
a few, so as to not overwhelm you, and also so you can be certain once you have
adjusted them all. They will tell you the total number of deprecated elements
you have outstanding.

Remember, there is no rush on this. These forms will continue to work as they
always have. (The actual changes in the code were made months ago.)

See earlier messages in this thread for explanations, and suggestions for
bulk-editing.

Rob