Sage: Ticket #14343: improve the installation guide for SageTeX
https://trac.sagemath.org/ticket/14343
<p>
The installation guide for SageTeX needs to be rearranged to be more friendly to beginning users. See <a class="ext-link" href="https://groups.google.com/d/topic/sage-edu/yhQoMuuLLv8/discussion"><span class="icon"></span>https://groups.google.com/d/topic/sage-edu/yhQoMuuLLv8/discussion</a> which links to <a class="ext-link" href="http://cunymathblog.commons.gc.cuny.edu/2012/04/09/sage/"><span class="icon"></span>this review of Sage</a>.
</p>
<p>
I will base any patch here on the results of <a class="closed ticket" href="https://trac.sagemath.org/ticket/14246" title="#14246: defect: installation guide has wrong location for SageTeX documentation (closed: fixed)">#14246</a>.
</p>
en-usSagehttps://trac.sagemath.org/chrome/site/logo_sagemath_trac.png
https://trac.sagemath.org/ticket/14343
Trac 1.2For batch modificationsTue, 17 Dec 2013 18:39:51 GMTmilestone changed
https://trac.sagemath.org/ticket/14343#comment:1
https://trac.sagemath.org/ticket/14343#comment:1
<ul>
<li><strong>milestone</strong>
changed from <em>sage-6.0</em> to <em>sage-6.1</em>
</li>
</ul>
TicketFor batch modificationsThu, 30 Jan 2014 21:20:52 GMTmilestone changed
https://trac.sagemath.org/ticket/14343#comment:2
https://trac.sagemath.org/ticket/14343#comment:2
<ul>
<li><strong>milestone</strong>
changed from <em>sage-6.1</em> to <em>sage-6.2</em>
</li>
</ul>
TicketFor batch modificationsTue, 06 May 2014 15:20:58 GMTmilestone changed
https://trac.sagemath.org/ticket/14343#comment:3
https://trac.sagemath.org/ticket/14343#comment:3
<ul>
<li><strong>milestone</strong>
changed from <em>sage-6.2</em> to <em>sage-6.3</em>
</li>
</ul>
TicketFor batch modificationsSun, 10 Aug 2014 16:51:03 GMTmilestone changed
https://trac.sagemath.org/ticket/14343#comment:4
https://trac.sagemath.org/ticket/14343#comment:4
<ul>
<li><strong>milestone</strong>
changed from <em>sage-6.3</em> to <em>sage-6.4</em>
</li>
</ul>
TicketDan DrakeThu, 27 Aug 2015 02:32:29 GMTcommit, branch, author set
https://trac.sagemath.org/ticket/14343#comment:5
https://trac.sagemath.org/ticket/14343#comment:5
<ul>
<li><strong>commit</strong>
set to <em>d6b008042a3af9bd03dab2288f9c5583b9875ae7</em>
</li>
<li><strong>branch</strong>
set to <em>u/ddrake/sagetex-install-guide-14343</em>
</li>
<li><strong>author</strong>
set to <em>Dan Drake</em>
</li>
</ul>
<p>
I've updated <code>doc/en/tutorial/sagetex.rst</code>. In particular:
</p>
<ul><li>I put the installation instructions above the example, since the example is useless until TeX can find <code>sagetex.sty</code>.
</li><li>The review of Sage describes a spectacularly unpleasant experience getting SageTeX to work. Some of his problems, I am sure, were related to the errant <code>sagetex.sty</code> that was included in TeXLive 2009 and which caused much misery. But it seems like he spent a long time trying to define systemwide environment variables. Yikes. So I demoted the <code>TEXINPUTS</code> bit in the installation guide.
</li><li>I included some info on symlinking, which is actually the very best way to let TeX find the <code>.sty</code> file.
</li><li>I updated the location of the source code, which is now in <code>...texmf/tex/latex/sagetex</code> instead of <code>...texmf/tex/generic/sagetex</code>.
</li><li>Some other cruft was deleted.
</li></ul><hr />
<p>
New commits:
</p>
<table class="wiki">
<tr><td><a class="ext-link" href="http://git.sagemath.org/sage.git/commit/?id=d6b008042a3af9bd03dab2288f9c5583b9875ae7"><span class="icon"></span>d6b0080</a></td><td><code>fix up doc/en/tutorial/sagetex.rst</code>
</td></tr></table>
TicketDan DrakeThu, 27 Aug 2015 04:44:34 GMTstatus changed
https://trac.sagemath.org/ticket/14343#comment:6
https://trac.sagemath.org/ticket/14343#comment:6
<ul>
<li><strong>status</strong>
changed from <em>new</em> to <em>needs_review</em>
</li>
</ul>
TicketKarl-Dieter CrismanThu, 27 Aug 2015 13:07:55 GMT
https://trac.sagemath.org/ticket/14343#comment:7
https://trac.sagemath.org/ticket/14343#comment:7
<p>
I like this overall but feel like
</p>
<pre class="wiki">+ mkdir -p TEXMFHOME/tex/latex
+ ln -s SAGE_ROOT/local/share/texmf/tex/latex/sagetex/sagetex.sty TEXMFHOME/tex/latex/sagetex.sty
</pre><p>
only works if people are always installing Sage in the same place every time, which might not be the case, especially if they are downloading binaries that are named after both the Sage version and the system (in the Mac app case, at the bottom of a long path via the app bundle). What do you think a good way to deal with that is? I don't want to have a crash course in filesystems, but this could be a (small) piece of the confusion.
</p>
<p>
Also, the "spectacularly unpleasant experience" is very similar to <a class="closed ticket" href="https://trac.sagemath.org/ticket/18951" title="#18951: defect: Instructions for using SageTeX with TeXShop (closed: fixed)">#18951</a>, or at least to the email I got which precipitated my opening that ticket... I wonder if sometimes following even one step wrong causes the other steps to just "not work"?
</p>
TicketDan DrakeThu, 27 Aug 2015 15:56:07 GMT
https://trac.sagemath.org/ticket/14343#comment:8
https://trac.sagemath.org/ticket/14343#comment:8
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/14343#comment:7" title="Comment 7">kcrisman</a>:
</p>
<blockquote class="citation">
<p>
I like this overall but feel like
</p>
<pre class="wiki">+ mkdir -p TEXMFHOME/tex/latex
+ ln -s SAGE_ROOT/local/share/texmf/tex/latex/sagetex/sagetex.sty TEXMFHOME/tex/latex/sagetex.sty
</pre><p>
only works if people are always installing Sage in the same place every time,
</p>
</blockquote>
<p>
Our releases have version and system stuff in the name, so users will have to copy the TeX stuff over...or rename their download so the symlink works. They have to do something and I don't know a good way to automate it. I wanted to add the symlink idea because that's what the TeXShop people suggest now -- and it's what I do.
</p>
<p>
Also, how do people actually run Sage? Don't they need to rename the sage-x.y.z directory? In the SageTeX documentation we always assume that "<code></code>sage<code></code>" is in their path, so how are users accomplishing that?
</p>
<p>
Should I just remove the symlink suggestion?
</p>
<blockquote class="citation">
<p>
Also, the "spectacularly unpleasant experience" is very similar to <a class="closed ticket" href="https://trac.sagemath.org/ticket/18951" title="#18951: defect: Instructions for using SageTeX with TeXShop (closed: fixed)">#18951</a>, or at least to the email I got which precipitated my opening that ticket... I wonder if sometimes following even one step wrong causes the other steps to just "not work"?
</p>
</blockquote>
<p>
For a certain class of users, I'm sure it does. If you have a poor understanding of Unix-like filesystems, paths, etc, then I'm sure it's easy to take one misstep and find yourself hopelessly lost.
</p>
TicketKarl-Dieter CrismanThu, 27 Aug 2015 17:54:46 GMT
https://trac.sagemath.org/ticket/14343#comment:9
https://trac.sagemath.org/ticket/14343#comment:9
<blockquote class="citation">
<p>
Our releases have version and system stuff in the name, so users will have to copy the TeX stuff over...or rename their download so the symlink works. They have to do something and I don't know a good way to automate it. I wanted to add the symlink idea because that's what the TeXShop people suggest now -- and it's what I do.
</p>
<p>
Also, how do people actually run Sage? Don't they need to rename the sage-x.y.z directory? In the SageTeX documentation we always assume that "<code></code>sage<code></code>" is in their path, so how are users accomplishing that?
</p>
<p>
Should I just remove the symlink suggestion?
</p>
</blockquote>
<p>
NO NO NO do not remove it! My point is just that perhaps there needs to be a reminder "there is this whole Unixy thing you need to do to make some of this work, and that includes having the <code>sage</code> in a specific spot as well as the folder itself with the same name each time. (Because just having <code>sage</code> in your path isn't the same as keeping it the same all the time; I have to manually redo the symlink for my Sage install when I upgrade my "main" Sage (as opposed to my development copy).
</p>
TicketClemens HeubergerFri, 25 Sep 2015 08:46:07 GMTmilestone changed
https://trac.sagemath.org/ticket/14343#comment:10
https://trac.sagemath.org/ticket/14343#comment:10
<ul>
<li><strong>milestone</strong>
changed from <em>sage-6.4</em> to <em>sage-6.9</em>
</li>
</ul>
<p>
Unfortunately, sage-6.9.beta7 still ships a version of sagetex which puts its files into <code>tex/generic</code>, cf. <a class="closed ticket" href="https://trac.sagemath.org/ticket/15900" title="#15900: defect: Move local/share/texmf/tex/generic/sagetex to ... (closed: fixed)">#15900</a>. So the note on "older versions of SageTeX" is not quite correct.
OTOH, this point will be moot once SageTeX 3.0 is merged (<a class="closed ticket" href="https://trac.sagemath.org/ticket/19072" title="#19072: defect: upgrade SageTeX to version 3.0 (closed: fixed)">#19072</a>).
</p>
TicketKarl-Dieter CrismanThu, 02 Mar 2017 18:26:44 GMTstatus changed
https://trac.sagemath.org/ticket/14343#comment:11
https://trac.sagemath.org/ticket/14343#comment:11
<ul>
<li><strong>status</strong>
changed from <em>needs_review</em> to <em>needs_info</em>
</li>
</ul>
<p>
What is the status here? Is it in fact obsolete? Also, see <a class="closed ticket" href="https://trac.sagemath.org/ticket/22499" title="#22499: enhancement: Move SageTeX to Sage repo (closed: invalid)">#22499</a> which might make dealing with this kind of thing easier.
</p>
TicketKarl-Dieter CrismanWed, 07 Jun 2017 12:58:16 GMT
https://trac.sagemath.org/ticket/14343#comment:12
https://trac.sagemath.org/ticket/14343#comment:12
<p>
Apparently Sage still at least in some places refers to SageTeX being on bitbucket, so that should be fixed too. Any file of the form <code>src/doc/**/tutorial/sagetex.rst</code> needs to be changed.
</p>
TicketKarl-Dieter CrismanThu, 30 Nov 2017 18:04:33 GMT
https://trac.sagemath.org/ticket/14343#comment:13
https://trac.sagemath.org/ticket/14343#comment:13
<p>
Given the move to sagemath/sagetex on GH, this ticket should now be only about retrieving any part of ddrake's branch that is not already in the user guide and still relevant. We've already improved the user guide incrementally over the years.
</p>
TicketKarl-Dieter CrismanMon, 07 Jan 2019 21:56:15 GMTstatus, milestone changed; author deleted
https://trac.sagemath.org/ticket/14343#comment:14
https://trac.sagemath.org/ticket/14343#comment:14
<ul>
<li><strong>status</strong>
changed from <em>needs_info</em> to <em>needs_review</em>
</li>
<li><strong>milestone</strong>
changed from <em>sage-6.9</em> to <em>sage-duplicate/invalid/wontfix</em>
</li>
<li><strong>author</strong>
<em>Dan Drake</em> deleted
</li>
</ul>
<p>
I think this can now be closed, as there have been enough changes that it would be very hard to figure out what should be done on this ticket (and you can't click on the branch in any case). I do encourage others (including myself) to open a new ticket with any specific new suggestions for improving the install guide!
</p>
TicketDima PasechnikThu, 10 Jan 2019 06:22:57 GMTstatus changed; reviewer set
https://trac.sagemath.org/ticket/14343#comment:15
https://trac.sagemath.org/ticket/14343#comment:15
<ul>
<li><strong>status</strong>
changed from <em>needs_review</em> to <em>positive_review</em>
</li>
<li><strong>reviewer</strong>
set to <em>Dima Pasechnik</em>
</li>
</ul>
TicketKarl-Dieter CrismanThu, 10 Jan 2019 13:34:44 GMTreviewer changed
https://trac.sagemath.org/ticket/14343#comment:16
https://trac.sagemath.org/ticket/14343#comment:16
<ul>
<li><strong>reviewer</strong>
changed from <em>Dima Pasechnik</em> to <em>Dima Pasechnik, Karl-Dieter Crisman</em>
</li>
</ul>
TicketErik BrayTue, 26 Feb 2019 13:58:00 GMTstatus changed; resolution set
https://trac.sagemath.org/ticket/14343#comment:17
https://trac.sagemath.org/ticket/14343#comment:17
<ul>
<li><strong>status</strong>
changed from <em>positive_review</em> to <em>closed</em>
</li>
<li><strong>resolution</strong>
set to <em>invalid</em>
</li>
</ul>
<p>
Presuming these are all correctly reviewed as either duplicate, invalid, or wontfix.
</p>
Ticket