Opened 8 years ago
Closed 2 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: |
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 7 years ago by
- Milestone changed from sage-6.0 to sage-6.1
comment:2 Changed 7 years ago by
- Milestone changed from sage-6.1 to sage-6.2
comment:3 Changed 7 years ago by
- Milestone changed from sage-6.2 to sage-6.3
comment:4 Changed 7 years ago by
- Milestone changed from sage-6.3 to sage-6.4
comment:5 Changed 6 years ago by
- Branch set to u/ddrake/sagetex-install-guide-14343
- Commit set to d6b008042a3af9bd03dab2288f9c5583b9875ae7
comment:6 Changed 6 years ago by
- Status changed from new to needs_review
comment:7 follow-up: ↓ 8 Changed 6 years ago by
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
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.styonly 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
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
- Milestone changed from sage-6.4 to sage-6.9
comment:11 Changed 4 years ago by
- 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
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 3 years ago by
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 2 years ago by
- 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 2 years ago by
- Reviewers set to Dima Pasechnik
- Status changed from needs_review to positive_review
comment:16 Changed 2 years ago by
- Reviewers changed from Dima Pasechnik to Dima Pasechnik, Karl-Dieter Crisman
comment:17 Changed 2 years ago by
- Resolution set to invalid
- Status changed from positive_review to closed
Presuming these are all correctly reviewed as either duplicate, invalid, or wontfix.
I've updated
doc/en/tutorial/sagetex.rst
. In particular:sagetex.sty
.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 theTEXINPUTS
bit in the installation guide..sty
file....texmf/tex/latex/sagetex
instead of...texmf/tex/generic/sagetex
.New commits:
fix up doc/en/tutorial/sagetex.rst