Commutative diagrams

[Sean Fitzpatrick]

I was about to post under support, and then I realized I was making a feature request that I *almost* know how to accomplish.

I was happy to see the announcement this morning on commutative diagrams, but realized that it won't support everything I need.

The trouble is that the ams cd package does not support curved arrows, and I have some diagrams in LaTeX that I want to port over to PreTeXt that have arrows.

Most of my old commutative diagrams were done using the 'xy' package (xypic) and the xymatrix environment.

There's some discussion of that here: https://groups.google.com/forum/#!msg/pretext-support/wEKBQRmuOHE/z1ZskGCBDgAJ

But I couldn't quite figure it out, and that particular thread fell off as everyone got busy.

(The problem there is that xy isn't natively supported in MathJax and there's some difficulty loading it due to naming mis-matches in packages between LaTeX and MathJax.)

An alternative to xypic with very similar syntax is tikzcd. This can be used with \usepackage{tikz-cd}, or with

\usepackage{tikz}

\usetikzlibrary{cd}

Pros and cons vs: xypic:

Con: uses TikZ, so image processing required.

Pro: uses TikZ, so no need to worry about MathJax.

Pro: easy to use if you're familiar with xy. See docuementation here: http://mirrors.ctan.org/graphics/pgf/contrib/tikz-cd/tikz-cd-doc.pdf

Pro: if you don't know how to use it, there's an app for that: https://tikzcd.yichuanshen.de/

You can draw your diagram and then export the code.

Con: diagrams are included as images, so you have to tinker with width settings, especially if you want fonts in the diagram to match fonts in the text.

The only problem is that the environment is tikzcd (\begin{tikzcd}...\end{tikzcd}) instead of tikzpicture.

Somewhere in the XSL I believe the appearance of \begin{tikzpicture} triggers the inclusion of the tikz package in the .tex file that is used to compile the image.

This doesn't get triggered with tikzcd.

If I put \usepackage{tikz} and \usetikzlibrary{cd} (or \usepackage{tikz-cd}) in the latex-image-preamble, I can build everything with MBX.

But if we have tikzcd and tikzimage in the same document, we probably don't want to load tikz there, right?

So what is best practice?

(a) figure out what to change in the XSL to load tikz when tikzcd is encountered, and put \usetikzlibrary{cd} in the image preamble, or

(b) put \usepackage{tikz-cd} in the image preamable

Option (b) gets the job done for a MWE, but could it conflict in larger projects?

[Thomas Judson]

You are absolutely correct in thinking that amscd will not do everything, but the point is that the amscd package is supported by MathJax and the other packages are not.  It’s an accessibility issue.  A screen reader should understand anything that is supported by MathJax.  On the other hand, anything done in tikz will not be understood easily by a screen reader—at least not at this point.

Tom

--
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 on the web visit https://groups.google.com/d/msgid/pretext-dev/c964d610-0de4-44cd-bdf8-4fac19786b43%40googlegroups.com.

[Sean Fitzpatrick]

Good point -- that is a 'con' with using tikz-cd.

I'm not sure if using xymatrix is a suitable middle ground but it's not supported without a fair bit of hacking. (Whereas tikz-cd requires one line added to the latex-image-preamble.)

The context I'm working on now is explaining the derivative as a linear transformation, in the context of the chain rule.

I want to write function composition with the arrow for the composition curving below, rather than writing this as a triangle.

I don't think I can do this with amscd.

As an aside/update for Rob: adding \usepackage{tikz-cd} to the image preamble is sufficient to get tikzcd to work - no XSL hacking required.

I ran it through a chapter of APEX that had tikz and asymptote with no side effects.

[Michael Doob]

TeX primitives allow very accurate drawing of (extensible) horizontal and vertical lines with various attachments

to make brackets, arrows and the like, but there is no support for lines at any other angle.  Leslie Lamport made

a move to improve this with his original picture environment by adding fonts that allows lines a few slopes (essentially

of the form m/n where 0 \leq m,n /leq 6, n \noteq  0. There are also some arcs for making circles and discs.

I believe that this is still supported in modern LaTeX distributions. Here is a MWE to try it out:

\documentclass{article}
\pagestyle{empty}
\begin{document}
A line with slope $2$:
\begin{picture}(100,100)
\put(0,0){\line(1,2){15}}
\end{picture}
\end{document}

I'm not sure if this helps or is at all supported, but at least it can be considered as an alternative.

Cheers,

Michael

[Rob Beezer]

On 1/17/20 2:28 PM, Sean Fitzpatrick wrote:
> As an aside/update for Rob: adding \usepackage{tikz-cd} to the image preamble is
> sufficient to get tikzcd to work - no XSL hacking required.
> I ran it through a chapter of APEX that had tikz and asymptote with no side effects.

Thanks - that is what I thought. Naive grep suggests that "\begin{tikzpicture}"
does not trigger anything special. "latex-image" is "latex-image".

I just documented fully the use of the amscd package, so when this thread
settles down, I'll see about adding this option for more complicated diagrams.
If you make a diagram with curved arrows, donating source and the mbx-generated
SVG would allow me to easily add an example to the sample article as well.

Rob

[Rob Beezer]

Thanks, Michael! The test for PTX would be to put this into the minimal article in

image/latex-image

and see if the latex conversion and the mbx SVG generation all went smoothly.

Not certain, but maybe Sean's triangular example could be achieved. And maybe
the "picture" enviromnent would be a conceivable feature request to the Speech
Rule Engine (MathJax accessibility component).

Rob

> https://tikzcd.yichuanshen.de/ <https://github.com/yishn/tikzcd-editor>

> You can draw your diagram and then export the code.
> Con: diagrams are included as images, so you have to tinker with width
> settings, especially if you want fonts in the diagram to match fonts in the
> text.
>
> The only problem is that the environment is tikzcd
> (\begin{tikzcd}...\end{tikzcd}) instead of tikzpicture.
>
> Somewhere in the XSL I believe the appearance of \begin{tikzpicture}
> triggers the inclusion of the tikz package in the .tex file that is used to
> compile the image.
> This doesn't get triggered with tikzcd.
>
> If I put \usepackage{tikz} and \usetikzlibrary{cd} (or \usepackage{tikz-cd})
> in the latex-image-preamble, I can build everything with MBX.
> But if we have tikzcd and tikzimage in the same document, we probably don't
> want to load tikz there, right?
>
> So what is best practice?
>
> (a) figure out what to change in the XSL to load tikz when tikzcd is
> encountered, and put \usetikzlibrary{cd} in the image preamble, or
> (b) put \usepackage{tikz-cd} in the image preamable
>
> Option (b) gets the job done for a MWE, but could it conflict in larger
> projects?
>

> --
> 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...@googlegroups.com>.

> To view this discussion on the web visit

> https://groups.google.com/d/msgid/pretext-dev/93df77e3-5222-4c82-a42a-1620fb01e6f0%40googlegroups.com
> <https://groups.google.com/d/msgid/pretext-dev/93df77e3-5222-4c82-a42a-1620fb01e6f0%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Alex Jordan]

I thought I detected some confusion in this thread, so I thought I'd post a PSA.

You can put just about any bit of tex into a latex-image, and it will come out fine.

Requirements:

1. Any packages it relies on need to be in docinfo/latex-image-preamble.
2. And tex macros need to either be in docinfo/latex-image-preamble or
   in docinfo/macros.
3. The "bit of tex" should be something that you would expect to work if
   you dropped it into a skeletal .tex file in between \begin{document} and
   \end{document}, with those packages and macros in the preamble. So
   for example, environments need to be opened and also closed.
4. No clashing with PTX-defined macros and environments.
   

So you can make xypic images this way, and it would be fine. (You should give

them description elements though.)

It's different when we start doing what we may now do with amscd, because

MathJax supports that. So no need for latex-image, just use "me" instead.

And in theory, no need for any kind of description, if MathJax is able to tell the

diagram structure to a screen reader user.

We still need a good way to do things like declare that you need the "xy"

MathJax extension and you need the "xypic" latex package.

To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-dev/06040ac9-915b-11b5-d50c-2c453a0b2763%40ups.edu.

[Sean Fitzpatrick]

I'll try to retrace my steps and do a couple of minimal examples. (For documentation the tikz-cd documentation has some nice examples.)

What I *think* I did:

I've got a section of my own that I use with Apex (but not endorsed by Greg!). I converted it to PreTeXt, and dropped it into my working version of that book.

Mbx hung on first pass, so I checked the source being generated and \usepackage{tikz} was missing from the preamble. Adding it let me compile the.tex file.

But we have lots of TikZ images, so presumably that package is being loaded when mbx runs through those.

I'll test again with a couple of latex-image examples, one with basic TikZ, one with pgfplots, one with tikz-cd, and see what happens.

By the way, for xypic diagrams, in LaTeX I load xy, not xypic, to get the \xymatrix environment. (I need a couple of options I don't remember, and I'm on my phone.)

If MathJax understands xy maybe I should try one and see what happens.

[Alex Jordan]

The Showcase Article

https://pretextbook.org/examples/showcase/html/latex-image.html

has tikz, pgfplots, and ps-tricks examples.

A nice addition could be a commutative diagrams section, separate

from the latex-images section.

--
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 on the web visit https://groups.google.com/d/msgid/pretext-dev/CAH%2BNcPbzYaVtWYYHvyTPBme334SsxNDu7Na4NOOK%2B4jQPvGCeA%40mail.gmail.com.

[Sean Fitzpatrick]

Probably should have some Asymptote examples in there too!

To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-dev/CA%2BR-jrd2qsnM-uuitvV0s_5Lyq5SemHd1kU-RXXW57MbXEHMqA%40mail.gmail.com.

[Sean Fitzpatrick]

Did some more testing to figure out why things did/didn't work.

First test used the minimal article, not APEX. So tikz was missing, and mbx failed. Reasonably so.

Second test used APEX. I assumed since there was no \usepackage{tikz} issued anywhere in the index.ptx file that PreTeXt was doing it automatically.

Not so -- APEX doesn't load TikZ, but it does load pgfplots. And pgfplots requires TikZ, so it gets pulled in.

So as long as either \usepackage{tikz} or \usepackage{pgfplots} is present in the latex-image-preamble, adding \usetikzlibrary{cd} is sufficient to get commutative diagrams working.

When in doubt, use \usepackage{tikz-cd} instead.

Tried using \xymatrix too. It works in a latex-image. Except: because it's not a TikZ image, the TikZ replacement code that handles the use of the \amp macro doesn't work.

So you have to use & amp ; in source rather than \amp.

Doesn't work in an <me>, as expected. I lack time/energy at the moment to figure out how to get that xyjax plugin for MathJax to work.

Also, realized I don't know a very basic PreTeXt thing: I can try putting <package>xy</package> in the latex-preamble (doesn't work, because of line above, but anyway..)

But I usually load this in LaTeX as \uspackage[all,cmtip]{xy}, and I don't know how to indicate the optional arguments! (Couldn't find anything documented.)

So maybe \xymatrix in <me> is better, if we can find a way to load xy into MathJax without rewriting XSL and/or hosting the extension on a local web server, and if it can then be accessed by screen readers.

In the meantime tikz-cd provides an easy replacement for me. (And the \amp macro works.)

[Rob Beezer]

Thanks, Sean! That all makes sense.

When a MathJax "extension" uses a name different from the "corresponding" LaTeX
package, then PreTeXt has no way to specify the discrepancy. There's an issue,
perhaps even traceable from here, or previous.

\amp is a convenience, perhaps from when we didn't even fully understand the XML
escape-character landscape ourselves.

Some packages allow you to specify options with a macro of their own. A good
example is:

\usepackage{geometry}
\geometry{a4paper}

Does "xy" not have such a mechanism? (Not unlikely.)

So it seems to me that most of this is fodder for documentation and working
examples for testing?

Thanks for chasing through all this.

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...@googlegroups.com>.

> To view this discussion on the web visit

> https://groups.google.com/d/msgid/pretext-dev/0bb4dc3f-a6a2-4e7f-a468-6f8a5dcaa912%40googlegroups.com
> <https://groups.google.com/d/msgid/pretext-dev/0bb4dc3f-a6a2-4e7f-a468-6f8a5dcaa912%40googlegroups.com?utm_medium=email&utm_source=footer>.

[David Farmer]

Am I correct that we want to have MathJax render all the commutative
diagrams it can (because of accessibility) and only use tikz-cd
when absolutely necessary?

> email to pretext-dev...@googlegroups.com.

> To view this discussion on the web visit

> https://groups.google.com/d/msgid/pretext-dev/f2105d66-f5c4-f956-c4bf-cbc7ace73da8%40ups.edu.
>

[Thomas Judson]

That’s my understanding.

> To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-dev/alpine.LRH.2.21.2001200617300.10019%40li375-150.members.linode.com.

[Sean Fitzpatrick]

Right. So hassle-free support for xy/xypic would greatly expand the number of diagrams where this is possible.

But that involves getting PreTeXt to ship with an unofficial MathJax extension that has to be installed separately on the host webserver.

And the issue already brought up with package naming being different in MathJax vs LaTeX.

The thread started by George awhile back suggests it's possible, but non trivial.

On Mon., Jan. 20, 2020, 6:16 a.m. Thomas Judson wrote:

That’s my understanding.

[Rob Beezer]

Right. And documentation now says "amscd" is recommended for exactly this
reason, including a note to this effect in the "what authors can/should do to
help accessibility" division.

I've not mentioned "tikz-cd" yet, but expect to add that to the documentation
soon as an alternative.

[Rob Beezer]

On 1/20/20 6:13 AM, Sean Fitzpatrick wrote:
> But that involves getting PreTeXt to ship with an unofficial MathJax extension
> that has to be installed separately on the host webserver.

That's a bit of a deal-breaker. We don't expect authors to configure servers,
and we have tried to minimize the management of other's packages.

However, there is a stock SVG (red video play button) that needs to be on the
server. There is XSL which creates the SVG and dumps it out with the rest of
the HTML. (A cute trick.)

I guess the XSL could read in a file (or several) and dump them back out again
during an HTML build, modulo escape characters, etc., but then we are
responsible for shipping that package, which becomes another maintenance chore.

What are the odds of "xypic" being made official? (With the "right" name?)
@Sean - you could cement your reputation as our liaison with external projects. ;-)

Rob

[Sean Fitzpatrick]

I can certainly post an issue on the MathJax GitHub page. See what Davide has to say...

Or ask the person who maintains the extension. I would guess that they've asked about inclusion.

--

[Sean Fitzpatrick]

Actually I'm not optimistic.

GitHub wiki for MathJax points to the third party extension. That extension hasn't seen a commit in over 4 years.

So I think it's abandoned.

[Rob Beezer]

On 1/20/20 8:54 PM, Sean Fitzpatrick wrote:
> Actually I'm not optimistic.
> GitHub wiki for MathJax points to the third party extension. That extension
> hasn't seen a commit in over 4 years.
>
> So I think it's abandoned.

That sounds like strike-three to me. It just means the usual "latex-image"
process and a less accessible HTML rendering. But it solves your optional
argument problem.

Of course, you could become maintainer of the MJ extension, and change the name
to match the LaTeX package. You know, with all your free time.

Rob

[Sean Fitzpatrick]

Ha!
I sent a message to the info@mathjax address but haven't heard anything
back.
If it has to go through latex-image anyway, I think tikz-cd is a good
replacement for xy, especially for authors who are already using TikZ
images elsewhere.

Somebody remind me this summer and maybe I'll fork xyjax.

[Sean Fitzpatrick]

I heard back from Davide on this: basically, we could, in principle, add a MathJax package with the right name that points to xy-jax, or a port thereof.

But there would be significant work involved to get a working port of xy-jax in MathJax v3. (And nobody around who's interested in taking that on, I think.)

So advice on using xypic I guess should either be "don't", or maybe more reasonably, "it needs to be wrapped in latex-image".