Instructions for using SageTeX with TeXShop

[kcrisman]

There have been many questions about this (e.g. http://ask.sagemath.org/question/8472/problems-with-sagetex-under-texshop/ and http://tex.stackexchange.com/questions/229473/having-trouble-getting-sagetex-working) and it's time we did something about it.

Unfortunately, I don't know that the author of TeXShop has any connection to Sage. See these release notes and the "About Sage.pdf" file included with TeXShop for how they do it. (These notes from a Sage user seem to more or less encapsulate this as well.)

There seem to be two types of issues. One is with TeXShop even finding sagetex.sty, and that seems to be PATH-related while in TeXShop - perhaps similar in nature to issues people have had on Linux or even the Windows 'app', though more hermetic due to Mac's closing off of the system. The other is with getting things to happen automatically and exactly how to move the .engine file to the right place in TeXShop (and I suppose also what to do with upgrades of TeXShop).

Finally, a good explanation of what to do when upgrading Sage (i.e. how to tell whether you need to upgrade SageTeX and how to do it) would be good here too.

Ideally more detailed instructions should be made fairly robust, at least for those with Mountain Lion and above.

CC: @dandrake @nilesjohnson

Component: documentation

Keywords: SageTeX

Reviewer: Karl-Dieter Crisman, Dan Drake

Issue created by migration from https://trac.sagemath.org/ticket/18951

[kcrisman]

comment:3

See also #13261, which is probably the same. Maybe this one is a little clearer in the description as to exactly what is needed.

[dandrake]

comment:4

I checked on a Mac running 10.9 with a recent version of TeXShop (3.2ish, 3.3ish, I think) and can't reproduce the problem. In fact, I can't imagine this really is a problem with TeXShop; TeX has its own path-searching mechanism and it would be really bizarre if TeXShop somehow altered that. If sagetex.sty is findable by TeX (via something like kpsewhich sagetex.sty in a terminal) then I would be very surprised if there's a problem when typesetting from TeXShop. I would need more information (and a Mac, since I don't have one these days) to figure out those problems.

Also, I see that TeXShop's changelog for 3.22 has exactly the correct solution to making the .sty file findable, even on upgrades; Ron Bannon's notes also have good advice. So I don't see anything to do as far as making the .sty file available; our own instructions, and those from the TeXShop folks, are all correct as far as I can see.

As for moving the .engine file: this isn't something we have control over. TeXShop ships with Sage's engine in the Inactive folder and you have to move the file. Once you've moved it, it should stay there; if it gets overwritten, then that's a TeXShop problem.

As for what you do when you upgrade Sage: it's the same as when you install it, unless you symlink sagetex.sty, in which case you do nothing. SageTeX has version mismatch detection, so if someone upgrades Sage (with a new version of SageTeX), they should see an error and be able to fix it by moving the .sty file appropriately.

I'm seeing a bunch of vague issues which are either not actually problems that we can solve, or for which we don't have actionable information. I'm marking this as "needs info", but I recommend we close it. The only thing I see here that we can do is add something to the installation guide about upgrading...but it already says you should recopy the directory. Do you want to mention symlinks?

[kcrisman]

Reviewer: Karl-Dieter Crisman, Dan Drake

[kcrisman]

comment:5

I think the update at #19072 is sufficient for now.