Opened 6 years ago

Closed 10 months ago

#20189 closed defect (invalid)

Update docs for new 'typical' dmg

Reported by: kcrisman Owned by:
Priority: major Milestone: sage-duplicate/invalid/wontfix
Component: user interface Keywords:
Cc: mgoerner, vbraun, iandrus, slelievre Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Status badges

Description (last modified by kcrisman)

#20119 adds a nicer dmg setting but we didn't fix the documentation, in particular src/bin/sage-README-osx.txt which says

------------
Installation
------------

Simply copy the application to your hard drive as you would any other
application.

which can be updated now. Also, does

There are two ways in which Sage can be distributed.  One is as a
"regular" OS X application named something like Sage-VERSION.  If you
see such an application, skip to the section about Sage.app.  If
instead you see a folder called "sage", proceed as follows.

1) Download the dmg somewhere and double click on it.

2) Drag the sage folder somewhere, e.g., /Applications

need to be updated, or is this still accurate (if indeed not relocatable after this process)?

Change History (14)

comment:1 Changed 6 years ago by vbraun

  • Priority changed from blocker to major

comment:2 Changed 6 years ago by kcrisman

  • Description modified (diff)

Priority changed from blocker to major

Really? We just change how we distribute the software and we decide making the documentation coincide with that isn't particularly important? Whatever.

comment:3 Changed 6 years ago by vbraun

Its important. Everything is important. But it doesn't give you wrong results.

comment:4 Changed 6 years ago by kcrisman

Well, if that's the criterion then I can point you to a slew of symbolics tickets that should be blockers :-) but again I'm not fighting this, though I hope my PR at the package thing will prove useful, if only in inspiration.

comment:5 Changed 6 years ago by kcrisman

On behalf of mgoerner, who apparently is having login problems on Trac:


These comments are still correct, but awkward explaining something that is self-explanatory, probably better to omit the "Installation" paragraph all together.

Just some more thoughts:

It would be better if we actually split the one long README file into two, one for each distribution type and change the Makefiles so that the relevant README file is copied to the root level of the dmg. That way we can get rid off the part of the introduction saying to which paragraph the reader should jump to.

There is some stuff that we can probably prune:

  • Information about OS X 10.4 - I don't think a lot of people are using 10.4 at this point. Do recent sage's even run on OS X 10.4?
  • The comment that one should use "cp -r ..." if finder can't copy it. I never ran into this. Is this still relevant?
  • "Select run it with Terminal"... It seems to me that in the last couple of versions of OS X finder does this automatically. If someone has old OS X versions around, it would be great if we could see when this is actually needed. Ideally, we could create a .DS_Store file in the sage directory that tells finder to run sage in a terminal on old OS X finder's.
  • "sage -bdist" - is now obsolete, see http://trac.sagemath.org/ticket/19673 - should such information be in a README file for users? Seems better suited we put such comments about the build process in, e.g., src/mac-app/Makefile.

Other thoughts:

  • consistently 80 chars per line
  • consistent formatting

And finally: Do we even need two different distributions .app.dmg and .dmg? Isn't the .app.dmg just enough? The filesize is pretty much exactly the same so that is not an argument. And with the symlink to the sage binary I added in http://trac.sagemath.org/ticket/20119, I wonder whether it is discoverable enough now for users who want to use it from the command line (maybe add a comment to the README?).

comment:6 follow-up: Changed 6 years ago by kcrisman

And finally: Do we even need two different distributions .app.dmg and .dmg? Isn't the .app.dmg just enough?

Well, possibly. One would certainly want to make it easily discoverable, not because someone using the app couldn't eventually find it, but because they won't want to waste time diving into the app bundle structure to figure out where it is.

comment:7 in reply to: ↑ 6 Changed 6 years ago by mgoerner

Replying to kcrisman:

And finally: Do we even need two different distributions .app.dmg and .dmg? Isn't the .app.dmg just enough?

Well, possibly. One would certainly want to make it easily discoverable, not because someone using the app couldn't eventually find it, but because they won't want to waste time diving into the app bundle structure to figure out where it is.

That is exactly why I added the symlink sage -> Contents/Resources?/sage/sage to the .app directory. Doesn't that count as easily discoverable?

comment:8 Changed 6 years ago by kcrisman

I haven't tried it yet, so I don't know. Probably? But they may not know how to find that on the command line. (Just brainstorming here.)

comment:9 Changed 5 years ago by kcrisman

Apparently it wasn't important enough for us to deal with then ... and then was lost. Is this still valid? (Probably.) I'll note one interesting thing, which is that now the Sage app bundles are *numbered* because of the release script binary-pkg, which broke some stuff in TeXShop - https://ask.sagemath.org/question/37828/sagetex-texshop-and-sageapp/

comment:10 Changed 12 months ago by mkoeppe

  • Cc slelievre added
  • Milestone changed from sage-7.1 to sage-duplicate/invalid/wontfix
  • Status changed from new to needs_review

Outdated, should close

comment:11 Changed 12 months ago by kcrisman

Just for clarification, does that mean the documentation everywhere (including in various readmes, on the website) says how to get Sage 9.3 in app form with the new app bundle? That would be phenomenal - I still get emails from people asking about this.

comment:12 Changed 12 months ago by mkoeppe

I think it was taken care of quite thoroughly in #31638. (The only place in our docs is in src/doc/en/installation/binary.rst.)

comment:13 Changed 12 months ago by kcrisman

  • Status changed from needs_review to positive_review

:thumbs-up-emoji:

comment:14 Changed 10 months ago by mkoeppe

  • Resolution set to invalid
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.