Opened 10 years ago

Closed 9 years ago

#6938 closed defect (fixed)

sage-README-osx.txt is non-sensical for a source distribution.

Reported by: drkirkby Owned by: tba
Priority: major Milestone: sage-4.6
Component: documentation Keywords:
Cc: drkirkby Merged in: sage-4.6.alpha1
Authors: Karl-Dieter Crisman Reviewers: John Palmieri
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Description

The file sage-README-osx.txt is very confusing. If someone downloads the source, the readme file indicates they have downloaded binaries.

There should perhaps be two README files - one for source, and one for binaries.

Change History (13)

comment:1 Changed 10 years ago by drkirkby

  • Cc david.kirkby@… added
  • Report Upstream set to N/A

comment:2 follow-ups: Changed 9 years ago by jhpalmieri

See also #5296.

By the way, I see two copies of the file "sage-README-osx.txt":

  • in the top-level directory: this one should be present in a binary distribution on OS X, not otherwise.
  • in SAGE_ROOT/local/bin. This one should be deleted. It doesn't seem to be tracked by Mercurial, so it needs to be removed by hand.

comment:3 in reply to: ↑ 2 Changed 9 years ago by kcrisman

Replying to jhpalmieri:

See also #5296.

By the way, I see two copies of the file "sage-README-osx.txt":

  • in the top-level directory: this one should be present in a binary distribution on OS X, not otherwise.
  • in SAGE_ROOT/local/bin. This one should be deleted. It doesn't seem to be tracked by Mercurial, so it needs to be removed by hand.

Hmm. But if both of these are not present in a source distribution, then where will it come from when sage -bdist is run? It has to be somewhere, right?

comment:4 in reply to: ↑ 2 Changed 9 years ago by kcrisman

  • Milestone set to sage-4.4
  • Status changed from new to needs_review

Replying to jhpalmieri:

See also #5296.

By the way, I see two copies of the file "sage-README-osx.txt":

  • in the top-level directory: this one should be present in a binary distribution on OS X, not otherwise.
  • in SAGE_ROOT/local/bin. This one should be deleted. It doesn't seem to be tracked by Mercurial, so it needs to be removed by hand.

Oh yeah, this one is needed for sage-bdist - see line 92:

    cp sage/local/bin/sage-README-osx.txt README.txt

But the one on the top level should be able to be safely removed, given that line in sage-bdist, methinks. Whether the one in /local/bin should overwrite the usual README.txt is another question.

Incidentally, the usual README.txt maybe should be updated - for instance, Mac OS X is essentially fully supported now, correct? And Fortran is now only included for OS X, not Linux, I believe.

Anyway, the correct course of action for this ticket is to remove the (untracked?) top-level OSX README file, as far as I can tell. How does one review this?

comment:5 follow-up: Changed 9 years ago by drkirkby

One option might be to have a file ".README-OSX-binary.txt" for information about binaries, and README-OSX.txt for information about source. Then if one runs sage -bdist, it replace README-OSX.txt with .README-OSX-binary.txt

The fact the file starts with a dot, would tend to make it less obvious. Or perhaps have one file, but make it a bit clearer what is relevant to those using a binary distribution, and what is relevant to those using a source distribution.

Dave

comment:6 in reply to: ↑ 5 ; follow-up: Changed 9 years ago by kcrisman

  • Status changed from needs_review to needs_work

Replying to drkirkby:

One option might be to have a file ".README-OSX-binary.txt" for information about binaries, and README-OSX.txt for information about source. Then if one runs sage -bdist, it replace README-OSX.txt with .README-OSX-binary.txt

Except for the dot, that is a good idea, and maybe a not hard way to fix this. Unfortunately, Macs automatically hide dot files in the Finder, and so most people would then have no README to see (unless they though to use ls -a in command line, which is not automatic for many).

The fact the file starts with a dot, would tend to make it less obvious. Or perhaps have one file, but make it a bit clearer what is relevant to those using a binary distribution, and what is relevant to those using a source distribution.

That is also a good solution. I'll try to work on this over the next week - isn't hard, just have to find time to do it.

comment:7 in reply to: ↑ 6 ; follow-up: Changed 9 years ago by drkirkby

Replying to kcrisman:

Replying to drkirkby:

One option might be to have a file ".README-OSX-binary.txt" for information about binaries, and README-OSX.txt for information about source. Then if one runs sage -bdist, it replace README-OSX.txt with .README-OSX-binary.txt

Except for the dot, that is a good idea, and maybe a not hard way to fix this. Unfortunately, Macs automatically hide dot files in the Finder, and so most people would then have no README to see (unless they though to use ls -a in command line, which is not automatic for many).

That was my whole point about using a dot - it would not be found easily.

If the information only relevant to those using a binary distribution was in a file starting with dot in the sources, then it would not be too obvious to those looking at the sources.

It would only become apparent on a binary distribution, because the act of running 'sage -bdist' would have removed the dot.

Dave

comment:8 in reply to: ↑ 7 ; follow-up: Changed 9 years ago by kcrisman

Replying to drkirkby:

Replying to kcrisman:

Replying to drkirkby:

One option might be to have a file ".README-OSX-binary.txt" for information about binaries, and README-OSX.txt for information about source. Then if one runs sage -bdist, it replace README-OSX.txt with .README-OSX-binary.txt

Except for the dot, that is a good idea, and maybe a not hard way to fix this. Unfortunately, Macs automatically hide dot files in the Finder, and so most people would then have no README to see (unless they though to use ls -a in command line, which is not automatic for many).

That was my whole point about using a dot - it would not be found easily.

If the information only relevant to those using a binary distribution was in a file starting with dot in the sources, then it would not be too obvious to those looking at the sources.

It would only become apparent on a binary distribution, because the act of running 'sage -bdist' would have removed the dot.

I understand now - I got confused by all the files and dots, sort of Dr. Seuss-esque. I'll definitely look into this soon.

comment:9 in reply to: ↑ 8 Changed 9 years ago by drkirkby

Replying to kcrisman:

Replying to drkirkby:

That was my whole point about using a dot - it would not be found easily.

If the information only relevant to those using a binary distribution was in a file starting with dot in the sources, then it would not be too obvious to those looking at the sources.

It would only become apparent on a binary distribution, because the act of running 'sage -bdist' would have removed the dot.

I understand now - I got confused by all the files and dots, sort of Dr. Seuss-esque. I'll definitely look into this soon.

It's one option, but I suspect a simpler one is to just have the one file be a bit more explicit about what is relevant to a source distribution, and what is relevant to a binary distribution.

I'm not overly concerned whether it is done in one file, two files, or whether any files are semi-hidden by the use of a dot in front of their name. But the current version is rather confusing.

comment:10 Changed 9 years ago by kcrisman

  • Authors set to Karl-Dieter Crisman
  • Status changed from needs_work to needs_review

Okay, this is mostly fixed by simply removing the README-osx file from the top directory. There is no HG for this, so it has to be removed by hand.

The place the one in /local/bin is copied to is in fact the top directory in a dmg/tgz only when bdisted, which is definitely very appropriate for this file!

So I don't think there is a need for any other changes, since any binary would be distributed with the OS X readme, but renamed to README.txt, in that very top directory, where anyone could read it. They would only have to read the usual README.txt in the sage/ directory if they wanted that sort of information, in which case the information in the OS X README is superfluous (i.e., they know how to use Terminal already).

Does that make any sense? My point is we don't need a separate README for any other purpose. I'm marking this needs review. I'm putting myself as an "author", but since I didn't actually write anything, if the reviewer disagrees then they can just make me a reviewer.

To release manager: Upon positive review, remove the sage-README-osx.txt in the top directory, leave the one in local/bin/ alone!

comment:11 Changed 9 years ago by kcrisman

  • Cc drkirkby added; david.kirkby@… removed

If #9433 is merged, this should probably get positive review and marked as merged. Of course, one could just merge this first anyway, before revision control is implemented :)

comment:12 Changed 9 years ago by jhpalmieri

  • Reviewers set to John Palmieri
  • Status changed from needs_review to positive_review

I'll give this a positive review. To the release manager: delete the file sage-README-osx.txt in the top directory.

I think doing this won't have any effect on #9433. If #9433 gets merged first, on the other hand, then this should automatically be taken care of.

comment:13 Changed 9 years ago by mpatel

  • Merged in set to sage-4.6.alpha1
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.