Update SageTeX documentation on use with TeXShop

[justin]

Section 2.3 of the SageTeX documentation ("Using TeXShop") is incomplete. It mentions the "%!TEX" string, but more details are either necessary or potentially helpful.

I have modified sagetex.dtx and attached an updated .spkg.

[justin]

New .spkg containing modified sagetex.dtx

[iandrus]

You should probably report this ​upstream as well.

[justin]

Replying to iandrus:

You should probably report this ​upstream as well.

Just checked the upstream site, but I don't see a way to report bugs. Am I missing something obvious?

[ddrake]

Replying to justin:

Just checked the upstream site, but I don't see a way to report bugs. Am I missing something obvious?

I don't know "obvious" it is, but I read sage-devel, so mentioning it there is as good as "reporting upstream". :) You can also email me directly.

I can pull a diff out of your spkg. I'll try to get to this later this week.

[jdemeyer]

Please fill in your real name as Author.

[kcrisman]

The changes apparently were done in the source itself, not with a patch, there is no SPKG.txt change, Mercurial change, etc., so this needs work. Notwithstanding that I'm sure the change itself is good - I struggled quite a while with exactly this issue a little over a year ago, so it's needed!

[kcrisman]

Here's the patch from the spkg.

src/sagetex.dtx

@@ -384 +384 @@
 %
 % Starting with version 2.25,
 % \href{http://www.uoregon.edu/~koch/texshop/}{\TeX Shop} includes
-% support for \ST. You must move the file |sage.engine| from
+% support for \ST. If you move the file |sage.engine| from
 % |~/Library/TeXShop/Engines/Inactive/Sage| to
-% |~/Library/TeXShop/Engines| in order for \TeX Shop to typeset a
-% file using \ST. Once the file |sage.engine| is placed in the
-% |Engines| directory, \TeX Shop should be restarted so that it recognizes
-% the new engine.
-
-% The engine is invoked in one of two ways.  The first is by selecting
-% it in the pulldown menu to the right of the "Typeset" button.  The
-% second is by putting the following line
-     |%!TEX TS-program = sage|
-% with the first 12 lines at the beginning of the .tex file in question.
-%  Note that, in this line, there must be exactly one space on either
-% side of the "=".  Either method assures that \TeX Shop will
-% automatically run Sage for you when compiling your document. Note that
-% the |"%TEX"| string is only useful when typesetting with \TeX Shop.
+% |~/Library/TeXShop/Engines| and put the line
+% \begin{quotation}
+%   |%!TEX TS-program = sage|
+% \end{quotation}
+% at the top of your document, then \TeX Shop will automatically run Sage
+% for you when compiling your document.
 %
 % Note that you will need to make sure that \LTX can find |sagetex.sty|
-% using any of the methods above. Unless you installed Sage in /Applications,
-% you will need to edit the |sage.engine| script to reflect the location of
-% your Sage installation.
+% using any of the methods above. You also might need to edit the
+% |sage.engine| script to reflect the location of your Sage
+% installation.
 %
 % \subsection{Other scripts included with \ST}
 % \label{sec:inst-other-scripts}

I wonder whether we should still keep the part about the pulldown menu; it's not in this patch, but why couldn't it be?

[kcrisman]

See also #18951, which is probably the same.

[ddrake]

Strangely, the above patch is in SageTeX. Original commit: ​https://github.com/dandrake/sagetex/commit/4f59c587; that is current: ​https://github.com/dandrake/sagetex/blob/master/sagetex.dtx#L381.

I propose this ticket be closed.

[kcrisman]

Okay, seems reasonable. I'll think more about #18951 - the problem is that a lot of that ticket came from someone experiencing problems that I couldn't verify since I wasn't on site, so it's possible there was some other issue, as you say.