improve the installation guide for SageTeX

[ddrake]

The installation guide for SageTeX needs to be rearranged to be more friendly to beginning users. See ​https://groups.google.com/d/topic/sage-edu/yhQoMuuLLv8/discussion which links to ​this review of Sage.

I will base any patch here on the results of #14246.

[ddrake]

I've updated doc/en/tutorial/sagetex.rst. In particular:

• I put the installation instructions above the example, since the example is useless until TeX can find sagetex.sty.
• 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 sagetex.sty 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 TEXINPUTS bit in the installation guide.
• I included some info on symlinking, which is actually the very best way to let TeX find the .sty file.
• I updated the location of the source code, which is now in ...texmf/tex/latex/sagetex instead of ...texmf/tex/generic/sagetex.
• Some other cruft was deleted.

---

New commits:

​d6b0080

fix up doc/en/tutorial/sagetex.rst

[kcrisman]

I like this overall but feel like

+      mkdir -p TEXMFHOME/tex/latex
+      ln -s SAGE_ROOT/local/share/texmf/tex/latex/sagetex/sagetex.sty TEXMFHOME/tex/latex/sagetex.sty 

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.

Also, the "spectacularly unpleasant experience" is very similar to #18951, 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"?

[ddrake]

Replying to kcrisman:

I like this overall but feel like

+      mkdir -p TEXMFHOME/tex/latex
+      ln -s SAGE_ROOT/local/share/texmf/tex/latex/sagetex/sagetex.sty TEXMFHOME/tex/latex/sagetex.sty 

only works if people are always installing Sage in the same place every time,

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.

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 "sage" is in their path, so how are users accomplishing that?

Should I just remove the symlink suggestion?

Also, the "spectacularly unpleasant experience" is very similar to #18951, 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"?

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.

[kcrisman]

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.

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 "sage" is in their path, so how are users accomplishing that?

Should I just remove the symlink suggestion?

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 sage in a specific spot as well as the folder itself with the same name each time. (Because just having sage 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).

[cheuberg]

Unfortunately, sage-6.9.beta7 still ships a version of sagetex which puts its files into tex/generic, cf. #15900. So the note on "older versions of SageTeX" is not quite correct. OTOH, this point will be moot once SageTeX 3.0 is merged (#19072).

[kcrisman]

What is the status here? Is it in fact obsolete? Also, see #22499 which might make dealing with this kind of thing easier.

[kcrisman]

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 src/doc/**/tutorial/sagetex.rst needs to be changed.

[kcrisman]

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.

[kcrisman]

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!

[embray]

Presuming these are all correctly reviewed as either duplicate, invalid, or wontfix.