Opened 9 years ago

Closed 3 years ago

#14343 closed enhancement (invalid)

improve the installation guide for SageTeX

Reported by: ddrake Owned by: mvngu
Priority: minor Milestone: sage-duplicate/invalid/wontfix
Component: documentation Keywords:
Cc: Merged in:
Authors: Reviewers: Dima Pasechnik, Karl-Dieter Crisman
Report Upstream: N/A Work issues:
Branch: u/ddrake/sagetex-install-guide-14343 (Commits, GitHub, GitLab) Commit: d6b008042a3af9bd03dab2288f9c5583b9875ae7
Dependencies: #14246 Stopgaps:

Status badges

Description

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.

Change History (17)

comment:1 Changed 8 years ago by vbraun_spam

  • Milestone changed from sage-6.0 to sage-6.1

comment:2 Changed 8 years ago by vbraun_spam

  • Milestone changed from sage-6.1 to sage-6.2

comment:3 Changed 7 years ago by vbraun_spam

  • Milestone changed from sage-6.2 to sage-6.3

comment:4 Changed 7 years ago by vbraun_spam

  • Milestone changed from sage-6.3 to sage-6.4

comment:5 Changed 6 years ago by ddrake

  • Authors set to Dan Drake
  • Branch set to u/ddrake/sagetex-install-guide-14343
  • Commit set to d6b008042a3af9bd03dab2288f9c5583b9875ae7

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:

d6b0080fix up doc/en/tutorial/sagetex.rst

comment:6 Changed 6 years ago by ddrake

  • Status changed from new to needs_review

comment:7 follow-up: Changed 6 years ago by 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"?

comment:8 in reply to: ↑ 7 Changed 6 years ago by 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.

comment:9 Changed 6 years ago by 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).

comment:10 Changed 6 years ago by cheuberg

  • Milestone changed from sage-6.4 to sage-6.9

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).

comment:11 Changed 5 years ago by kcrisman

  • Status changed from needs_review to needs_info

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

comment:12 Changed 4 years ago by 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.

comment:13 Changed 4 years ago by 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.

comment:14 Changed 3 years ago by kcrisman

  • Authors Dan Drake deleted
  • Milestone changed from sage-6.9 to sage-duplicate/invalid/wontfix
  • Status changed from needs_info to needs_review

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!

comment:15 Changed 3 years ago by dimpase

  • Reviewers set to Dima Pasechnik
  • Status changed from needs_review to positive_review

comment:16 Changed 3 years ago by kcrisman

  • Reviewers changed from Dima Pasechnik to Dima Pasechnik, Karl-Dieter Crisman

comment:17 Changed 3 years ago by embray

  • Resolution set to invalid
  • Status changed from positive_review to closed

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

Note: See TracTickets for help on using tickets.