Display math maintenance

[Rob Beezer]

Heads-up. I'm doing some maintenance on display math. Nobody should get caught
out, and there should not be any change in output. But if you see any
goofieness (or worse) with #md or #mdn please report it sooner rather than
later. Thanks.

For the idly curious: #md and #mdn should always have #mrow children. Right now
I am just making that assumption explicit in the templates that match these
elements. I have no idea how bad it is when these elements do not have #mrow
children, so I can't imagine anybody has this in their source. So, again, this
is not an attempt to catch anybody out.

Rob

[David W. Farmer]

Can I hope that this is a step to eliminating the #me and #men
tags, as those will just become #md and #mdn with no #mrow
child?

Regards,

David

> --
> 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/MTAwMDAwNS5iZWV6ZXI.1761068996%40pnsh.
>

[Rob Beezer]

You can do more than just hope.

Exactly that. I was wondering how long it would be before somebody goes there.
Cat is out of the bag. You get the prize. That was fast.

Phase 1. Will sit for a bit, but not long.

Phase 2. Quietly enable #md, #mdn with no #mrow and a single equation's worth
of LaTeX.

Phase 3. Pre-process #me, #mdn to the equivalent #md, #mdn forms.

Phase 4. Move everybody along, including documentation and samples. Ugh.

Phase 2 will be the most delicate.

I'd love to get rid of #mdn and make numbering a #docinfo global choice with
attribute overrides. We have some of that on #mrow. But building the actual
numbers might be really gruesome until that code improves on its own.

Watch this space. Or just keep hoping. ;-)

Rob

[Rob Beezer]

A "bare" #md or #mdn is display mathematics with no #mrow children.
Functionally, they are isomorphic to the current #me and #men elements. So
their content is a single line of LaTeX, with no alignment suggested or implemented.

With a whole lot of very detailed work, the "bare" versions should now be
available for testing. This is *not* an announcement of production-ready code,
nor any kind of deprecation. But it is a good time to experiment. Insider news
for developers.

On a branch, try a few examples. Perhaps the numbered version in among other
numbered equations.

A real test is to add in the XSL below. This goes naturally in
pretext-assembly.xsl, but I think you can plop it in lots of other places. It
will convert *all* of your one-line display math temporarily on-the-fly. Then
you can do a before/after diff on your output from various conversions.

<xsl:template match="me" mode="repair">
<md>
<xsl:apply-templates select="node()|@*" mode="repair"/>
</md>
</xsl:template>
<xsl:template match="men" mode="repair">
<mdn>
<xsl:apply-templates select="node()|@*" mode="repair"/>
</mdn>
</xsl:template>

* DO NOT start using these permanently in your projects.

* DO NOT convert your existing #me or #men yet.

* DO test and report any discrepancies. Note you will want to use the
pretext/pretext script for this sort of testing.

* NOTE: if you read the commits or the XSL you will see a lot of matches that
look like x[y]|x[not(y)] which is really stupid since it can be replaced by
simply x. Once this all settles down there is a lot of clean-up like this
which will be appropriate.

The plan is to add the above pre-processor conversion, and deprecate #me and
#men. Then #mdn is on the chopping block, but that's going to be a harder
problem since it has implications for numbering.

[Rob Beezer]

As part of this push to remove some superfluous elements, I have employed the
pre-processor to record when an "mrow" will be numbered, or not. This approach
will be extended to more reliably work with numbered equations. You should not
see any change, but if you do, please post here. Thanks.

Rob

[Rob Beezer]

More progress to report and to test.

* As announced earlier, the #md element now comes in two versions:

- "Original" with #mrow children
- "Extra Crispy", no, wait
- "Bare" with no #mrow children

The latter is meant to mimic #me and #men.

* We have always had the #mrow/@number attribute ('yes'/'no') to override the
numbering choice implied by #md or #mdn for a single #mrow.

* Now you can put @number on #md and effect a default choice for that
entire display (original or bare). This will let #md behave just like #me,
#men, and #mdn. (Finally!)

* There is now a docinfo/numbering/@equations attribute that will set a
document-wide default. The default default, is "no", as it would be for #me
and #md (the "n-less" elements). So you can go all-numbers or no-numbers and
handle exceptions with the above mechanisms.

Now would be an excellent time to test! Please. You were looking for a way to
help weren't you? Just try a few things with your project. The sample article
has some examples in Chapter 7 (not yet updated). I'll chat with Oscar tomorrow
about movement to the CLI.

Note: the "global" default is not really global yet, it only applies to #md
elements (and their contained #mrow).

Next: halfway through this (the worst possible time!), I realized that I could
use the pre-processor to convert a bare #md into a solo-#mrow #md, and really
simplify a bunch of code. We will do that work once this settles down and it
should all be under the hood. That said, here is the current repair template
(not merged!) that will either (a) put into code some of the words above, or (b)
give the adventureous something to play with.

<xsl:template match="me|men|mdn" mode="repair">
<xsl:element name="md">
<xsl:apply-templates select="@*" mode="repair"/>
<xsl:attribute name="number">
<xsl:choose>
<xsl:when test="self::me">
<xsl:text>no</xsl:text>
</xsl:when>
<xsl:when test="self::men">
<xsl:text>yes</xsl:text>
</xsl:when>
<xsl:when test="self::mdn">
<xsl:text>yes</xsl:text>
</xsl:when>
</xsl:choose>
</xsl:attribute>
<xsl:apply-templates select="node()" mode="repair"/>
</xsl:element>
</xsl:template>

Rob

[Rob Beezer]

More progress to report on this front. (This was meant to go out a few days
ago, but got caught in my ongoing screw-ups with email, I think).

We have *six* ways to author displayed equations:

1. me

2. men

3. md (with mrow children)

4. mdn (with mrow children)

5. md (no children, just LaTeX content, "bare")

6. mdn (no children, just LaTeX content)

(1), (2) and (4) are slated to be deprecated. (6) is new, and will have a very
short lifetime, please do not use it in production. (5) is new, and useful
going forward. That leaves (3), which is the most important going forward.

(3) and (5) will now be the supported forms. Right now, with no real
announcement, the pre-processor is converting all six forms into (3), and the
code needs only accomodate that construction (vastly simplifying the code!).

Aah, what about numbered equations, I hear you ask. How will that work? The
@number attribute, with values "yes" and "no"

A. has always been supported on #mrow.

B. is now supported on (3) and (5), with values from (A) taking precedence.

C. docinfo/numbering/@equations can be "yes" or "no" for a document-wide
default, with from (A) and (B) taking precedence.

Please report any problems you uncover with display math. General
announcements, deprecation warnings, etc. will come soon.

[Rob Beezer]

As promised, the bare #mdn construction (no #mrow children, see (6) below) has
outlived its usefulness in this transition and will now be dropped if authored,
with a warning. It never had full support really, anyway, and was only
announced here.

I continue to push lots of refinement and clean-up. All very worthwhile, but
way more to do than I had imagined. Code comments, sample article refinemaents,
and The Guide are all documentation chores that need addressing. Then an
announcement.

As this code hits the CLI, please, at a minimum, try using it in anything new
you write.

Rob