Update SageTeX documentation on use with TeXShop

[RalphieBoy]

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.

Component: documentation

Keywords: TeX, SageTeX

Reviewer: Dan Drake

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

[RalphieBoy]

New .spkg containing modified sagetex.dtx

[RalphieBoy]

comment:1

Attachment: sagetex-2.3.3.p3.spkg.gz

[RalphieBoy]

Changed keywords from none to TeX, SageTeX

[gvol]

comment:2

You should probably report this upstream as well.

[RalphieBoy]

comment:3

Replying to @gvol:

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?

[dandrake]

comment:4

Replying to @RalphieBoy:

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]

comment:5

Please fill in your real name as Author.

[RalphieBoy]

Changed author from justin to Justin C. Walker

[kcrisman]

comment:7

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]

comment:8

Here's the patch from the spkg.

diff -Naur sagetex-2.3.3.p3/src/sagetex.dtx sagetex-2.3.3.p2/src/sagetex.dtx
--- sagetex-2.3.3.p3/src/sagetex.dtx    2012-07-16 16:25:17.000000000 -0400
+++ sagetex-2.3.3.p2/src/sagetex.dtx    2012-01-16 01:40:54.000000000 -0500
@@ -384,27 +384,19 @@
 %
 % 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]

comment:13

See also #18951, which is probably the same.

[dandrake]

comment:14

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

I propose this ticket be closed.

[kcrisman]

comment:15

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.

[kcrisman]

Reviewer: Dan Drake

[kcrisman]

Changed author from Justin C. Walker to none