[with patches, positive review] Citation instructions for Sage

[jason]

William Stein writes:

Yes to every single one of your questions.

On Dec 3, 2007 1:29 PM, Jason Grout <jason-sage@creativetrax.com> wrote:
> >
> > I'm citing Sage in a paper I'm writing.  After searching (using the
> > search function at sagemath.org) and clicking around lots of places, I
> > found the page in the tutorial:
> >
> > http://sagemath.org/doc/html/tut/node62.html
> >
> > and the more official instructions at:
> >
> > http://sagemath.org/pub.html
> >
> > A couple of questions:
> >
> > 1. The instructions in the two places conflict each other.  Should we
> > change the tutorial to match http://sagemath.org/pub.html (or point to it?)
> >
> > 1. If I remember correctly, a while ago William encouraged people to use
> > "Sage" instead of "SAGE", saying that we had outgrown the acronym.  If
> > so, there are a _lot_ of occurrences of SAGE that need to replaced in
> > the documentation and website.  Should we change the citing instructions
> > to use "Sage" instead of "SAGE"?
> >
> > 3. Every time I look for the citation instructions, I spend at least
> > 15-20 minutes searching and clicking different places.  I think the
> > publication page is great marketing material (and a great source of
> > example Sage code in real life).  Can we link to the publication page
> > from the main page and indicate that the citation instructions are also
> > there?
> >
> > Thanks,
> >
> > Jason
> >
> >
>> > >
> >



-- William Stein 
Associate Professor of Mathematics 
University of Washington 
http://wstein.org 

[jason]

I took care of the second "#1" in the email on the wiki:

 http://wiki.sagemath.org/Publications_using_SAGE

[mvngu]

Here are some possible trivial fixes:

1. From Status of Development

   -SAGE: Timeline
   +Sage: Timeline
   

2. From Sage developers around the world 2.1 Within the "Tom Boothby" row

   -The SAGE Notebook
   +The Sage Notebook
   

   2.2 Within the "Wilson Cheung" row

   -Compilation of SAGE on Solaris
   +Compilation of Sage on Solaris
   

   -discussion of SAGE build process
   +discussion of Sage build process
   

   2.3 Within the "Alex Clemesha" row

   -SAGE's 2d plotting functionality
   +Sage's 2d plotting functionality
   

   2.4 Within the "John Cremona" row

   -C++ part of SAGE interface to mwrank, Tables
   +C++ part of Sage interface to mwrank, Tables
   

   -organize SAGE Days 6
   +organize Sage Days 6
   

   2.5 Within the "Doug Cutrell" row

   -created the SAGE Microsoft Windows installer
   +created the Sage Microsoft Windows installer
   

   2.6 Within the "David Kirkby" row

   -Compilation of SAGE on Solaris
   +Compilation of Sage on Solaris
   

   -much help on general SAGE build process
   +much help on general Sage build process
   

   2.7 Within the "Jason Martin" row

   -work on SAGE 64-bit build
   +work on Sage 64-bit build
   

   2.8 Within the "Kate Minola" row

   -improvement on building SAGE components
   +improvement on building Sage components
   

   2.9 Within the "Bobby Moretti" row

   -SAGE library distribution
   +Sage library distribution
   

   -SAGE chroot jail
   +Sage chroot jail
   

   -SAGE .deb
   +Sage .deb
   

   2.10 Within the "Bill Page" row

   -SAGE's AXIOM interface
   +Sage's AXIOM interface
   

   2.11 Within the "Yi Qiang" row

   -Distributed SAGE (in progress)
   +Distributed Sage (in progress)
   

   2.12 Within the "Gary Zablackis" row

   -created all SAGE binaries for MS windows from
   +created all Sage binaries for MS windows from
   

3. From Acknowledgment to Supporters

   -(Check that the selected fund is the "SAGE Foundation").
   +(Check that the selected fund is the "Sage Foundation").
   

   -SAGE Days 6 Workshop (November 10 – 14, 2007)
   +Sage Days 6 Workshop (November 10 – 14, 2007)
   

   -SAGE Days 5 Workshop (Sept 30–Oct 3, 2007)
   +Sage Days 5 Workshop (Sept 30–Oct 3, 2007)
   

   -Grant No. 0555776, Grant No. 0713225 for 2007-2010 (the SAGE Postdoc)
   +Grant No. 0555776, Grant No. 0713225 for 2007-2010 (the Sage Postdoc)
   

   -a Mary Gates Scholarship for work on SAGE.
   +a Mary Gates Scholarship for work on Sage.
   

   -for providing the SAGE lab (Sieg Hall 312).
   +for providing the Sage lab (Sieg Hall 312).
   

   -hosted and funded SAGE Days 3 and SAGE Days 7.
   +hosted and funded Sage Days 3 and Sage Days 7.
   

4. From Publications, publication items 4 and 20 both have "SAGE" in their names. I'm not sure it's a good idea to change those occurrences of "SAGE" to "Sage".

5. From Success Stories, Testimonials and News Articles 5.1 For testimonial "Martin Rubey, FriCAS-devel"

   -Just about *all* math colleagues I know are starting to use SAGE now, and
   +Just about *all* math colleagues I know are starting to use Sage now, and
   

   5.2 For testimonial "#73, Sage Survey 2008"

   -find what I need in SAGE for my work. Many thanks to your team. You guys have
   +find what I need in Sage for my work. Many thanks to your team. You guys have
   

   5.3 For testimonial "David Joyner, 2008-07-15"

   -I used SAGE for some sections of a differential equations course I was teaching
   +I used Sage for some sections of a differential equations course I was teaching
   

   -SAGE so I made the assignments worth very little and very easy. Also, I made
   +Sage so I made the assignments worth very little and very easy. Also, I made
   

   -did the extra credit ones too and say that they liked SAGE and its philosophy.
   +did the extra credit ones too and say that they liked Sage and its philosophy.
   

   5.4 For testimonial "Roland, sage-edu, 2008-08-13"

   -SAGE. I just give examples and not lines of code, mainly because to promote the
   +Sage. I just give examples and not lines of code, mainly because to promote the
   

   -usage of SAGE and to encourage others to check the results found.
   +usage of Sage and to encourage others to check the results found.
   

   -The following output comes from a SAGE notebook: 1 = 3+5-7 , 2 = 3+7-8 , 3 = 3
   +The following output comes from a Sage notebook: 1 = 3+5-7 , 2 = 3+7-8 , 3 = 3
   

   -b. Less easy. Is 3,5,7,8 the best 4-tuple? Two ways to answer this using SAGE:
   +b. Less easy. Is 3,5,7,8 the best 4-tuple? Two ways to answer this using Sage:
   

   -in SAGE", or you can allow also negative numbers and look for the longest
   +in Sage", or you can allow also negative numbers and look for the longest
   

   -of numbers 0..75 as the following SAGE output shows:
   +of numbers 0..75 as the following Sage output shows:
   

   -To conclude: SAGE helped me to find relative simple exercises and questions to
   +To conclude: Sage helped me to find relative simple exercises and questions to
   

   -become aware of the depth of even simple mathematics. I learned from SAGE
   +become aware of the depth of even simple mathematics. I learned from Sage
   

   5.5 For the news item 'Sage winner of the 2007 "Trophées du Libre"'

   -SAGE (United States) put forward by William Stein
   +Sage (United States) put forward by William Stein
   

   -SAGE makes it possible to study and use a huge range of mathematics, including
   +Sage makes it possible to study and use a huge range of mathematics, including
   

6. From  Sage online notebook

   -Sign up for a new SAGE Notebook account
   +Sign up for a new Sage Notebook account
   

   I've also noticed the same typo at the following mirrors:

   https://sage.math.washington.edu:8103
   https://sage.math.washington.edu:8102
   http://sage.milnix.org
   

7. From  https://secure.gifts.washington.edu/as_mathematics/gift.asp?page=make&Code=MATSAG

   -The SAGE Foundation
   +The Sage Foundation
   

8. From  http://groups.google.com/group/sage-edu

   -or education-related ideas or questions relating to SAGE.
   +or education-related ideas or questions relating to Sage.
   

9. From http://www.sagemath.org/packages/standard/

   -SAGE Standard Packages
   +Sage Standard Packages
   

10. From http://www.sagemath.org/packages/optional

    -SAGE Optional Packages
    +Sage Optional Packages
    

11. From http://www.sagemath.org/packages/experimental

    -SAGE Experimental Packages
    +Sage Experimental Packages
    

[jason]

Wow, thanks for all your work!

[schilly]

about number 5: when i compiled the collection of quotes, i wanted them to be real quotes. I thought about replacing the wrong Sage capitalizations but i rejected it. Do you think it should be replaced?

The same holds for the publications. They are written in that way, the past cannot be changed ;)

[mvngu]

Replying to schilly:

about number 5: when i compiled the collection of quotes, i wanted them to be real quotes. I thought about replacing the wrong Sage capitalizations but i rejected it. Do you think it should be replaced?

The same holds for the publications. They are written in that way, the past cannot be changed ;)

Well, you're absolutely right on this point, hence my comment "Here are some _possible_ trivial fixes:", emphasis added. But I wanted to collect those "suggestions" here for future reference.

Regards,
Minh Van Nguyen

[mvngu]

This attachment fixes citations of Sage in the file "<sage-home-dir>/COPYING.txt".

[mvngu]

Fixes citations of Sage in the file "<sage-home-dir>/README.txt".

[mvngu]

Fixes citations of Sage in the file "sage-3.1.2/sage-README-osx.txt".

[kcrisman]

Fixes SAGE to Sage in version() etc.

[kcrisman]

Most patches here should be trivial to review, though some may require rebasing.

This ticket perhaps should have an ongoing existence - as patches are merged, new ones could still be added.

[jhpalmieri]

Here's a patch to deal with the first item 1 in the description: fix the conflict in citation instructions between the tutorial and sagemath.org.

[jhpalmieri]

Of the patches here:

copying.patch,
readme.patch,
readmeOSX.patch,

all look okay: the changes are pretty trivial. mercurial-howto.patch I think is no longer needed, since I think that file has been deleted. Right?

10737.patch actually changes some code, so is slightly less trivial. It looks good, too.

I'll give a positive review to all of these. Two things:

1. After applying 10737.patch, the output from

   sage: banner()
   

is

----------------------------------------------------------------------
| Sage Version 3.1.4, Release Date: 2008-10-16                       |
| Type notebook() for the GUI, and license() for information.        |
----------------------------------------------------------------------

which is not the same as what I see when I start up Sage:

----------------------------------------------------------------------
| SAGE Version 3.1.4, Release Date: 2008-10-16                       |
| Type notebook() for the GUI, and license() for information.        |
----------------------------------------------------------------------
Loading SAGE library. Current Mercurial branch is: clone

Note the two instances of "SAGE" here. Where is this string coded?

2. My patch to the tutorial needs review.

[jhpalmieri]

Replying to jhpalmieri:

Note the two instances of "SAGE" here. Where is this string coded?

Okay, found them. One instance is in a script 'sage-banner', and another is in misc.py. Patches attached.

I'm beginning to agree with kcrisman that we maybe should merge some of these when we can, then get to the others later...

[jhpalmieri]

patch misc.py, changing SAGE to Sage

[jhpalmieri]

change SAGE to Sage in various scripts (e.g. sage-banner)

[jhpalmieri]

I would comment that I don't know how to easily check (e.g., doctest) the changes that I made to the scripts. Please referee carefully.

[mvngu]

Replying to jhpalmieri: [...]

2. My patch to the tutorial needs review.

The patch "1389-tut.patch" looks good to me. However, here are some further changes to that patch:

1.

-If you use Sage in a book, paper, website, etc., please email William
-Stein and reference Sage as follows:
+If you use \SAGE in a book, paper, website, etc., please email William
+Stein and reference \SAGE as follows:

2. The following change reflects the BibTeX entry:

   -William Stein, Sage Mathematics Software (version x.y.z),
   +William Stein, Sage: Open Source Mathematical Software (version x.y.z),
   

3.

-where you should change x.y.z. to the version of Sage that you used
-for the paper. In Bibtex:
+where you should change x.y.z. to the version of \SAGE that you used
+for the paper. In BibTeX:

4.

-Year = 2008}
+Year = {2008}

5.

-Also, be sure to find out what components of Sage, e.g., Numpy, PARI,
+Also, be sure to find out what components of \SAGE, e.g., NumPy, PARI,

6.

-finding out who wrote the Sage code you're using and acknowledge them
+finding out who wrote the \SAGE code you're using and acknowledge them

[mvngu]

Replying to jhpalmieri: [...]

mercurial-howto.patch I think is no longer needed, since I think that file has been deleted. Right?

Not exactly. It's shipped with sage-3.1.3 source distribution in the directory

<sage-parent-dir>/sage-3.1.3/devel/sage-main/mercurial-howto.txt

But perhaps it'll be removed in sage-3.2?

The patch 1389-misc.patch looks good to me.

[mabshoff]

Replying to mvngu:

But perhaps it'll be removed in sage-3.2?

It is gone in Sage 3.1.4.

This ticket is really messy by now. Can someone in detail list the patches that need to be applied in which order to which repo?

Cheers,

Michael

[jhpalmieri]

There is a new version of the tut patch, taking the comments into consideration. Note:

Replying to mvngu:

4.

-Year = 2008}

+Year = {2008}

I made a change like this, but changing 2008} to {2008}}. The second brace } matches the one a few lines earlier, in the line @manual{sage. (The change wasn't really necessary, but it doesn't hurt, either.)

[jhpalmieri]

Replying to mabshoff:

This ticket is really messy by now. Can someone in detail list the patches that need to be applied in which order to which repo?

The patches copying.patch, readme.patch, readmeOSX.patch all affect files at the top-level of SAGE_ROOT. I don't know if there is a corresponding repository for those, so they might need to be applied by hand.

Produced using hg_sage: 10737.patch, 1389-misc.patch.

Produced using hg_doc: 1389-tut.patch.

Produced using hg_scripts: 1389-scripts.patch. This one hasn't been reviewed yet; the others all seem to have positive reviews.

As far as I can tell, these can be applied in any order.

Share and Enjoy.

John

[mvngu]

Replying to mvngu:

4. From Publications, publication items 4 and 20 both have "SAGE" in their names. I'm not sure it's a good idea to change those occurrences of "SAGE" to "Sage".

I think we can leave publication item 4 alone. The only occurrence of "SAGE" for that item is from a quoted text within a paper: "On page 10 they write "These performance numbers were obtained using the SAGE library."

5. From Success Stories, Testimonials and News Articles

I agree with schilly that all quoted texts from this URL should be left alone.

7. From  https://secure.gifts.washington.edu/as_mathematics/gift.asp?page=make&Code=MATSAG

-The SAGE Foundation
+The Sage Foundation

The diff hasn't been applied yet.

9. From http://www.sagemath.org/packages/standard/

-SAGE Standard Packages
+Sage Standard Packages

The diff hasn't been applied yet.

10. From http://www.sagemath.org/packages/optional

-SAGE Optional Packages
+Sage Optional Packages

The diff hasn't been applied yet.

11. From http://www.sagemath.org/packages/experimental

-SAGE Experimental Packages
+Sage Experimental Packages

The diff hasn't been applied yet.

Apart from the above comments, all other diffs at comment 3 has been applied.

[schilly]

Replying to mvngu:

... http://www.sagemath.org ... change those occurrences of "SAGE" to "Sage".

Hi, I'm well aware of all those old uppercase occurrencies on the website. I just have to finish another project, then I'll redo the packages, download and all other sites like that. Those are old scripts that I'll replace. Don't worry.

Though, the donation page for the foundation is still unclear, since it could be registered by the uppercase version and therefore it simply has this name, but shouldn't be a problem.

Harald

[mvngu]

Replying to jhpalmieri:

There is a new version of the tut patch, taking the comments into consideration.

The revised patch 1389-tut.patch looks good. Here's another change to that patch:

-where you should change x.y.z. to the version of Sage that you used
+where you should change x.y.z to the version of \SAGE that you used

[jhpalmieri]

change citation in tutorial to match sagemath.org (revised revised version)

[jhpalmieri]

Replying to mvngu:

Replying to jhpalmieri:

There is a new version of the tut patch, taking the comments into consideration.

The revised patch 1389-tut.patch looks good. Here's another change to that patch:
-where you should change x.y.z. to the version of Sage that you used
+where you should change x.y.z to the version of \SAGE that you used

Fixed in the newest patch.

[mvngu]

Replying to jhpalmieri:

Replying to mvngu:

Replying to jhpalmieri:

There is a new version of the tut patch, taking the comments into consideration.

The revised patch 1389-tut.patch looks good. Here's another change to that patch:
-where you should change x.y.z. to the version of Sage that you used
+where you should change x.y.z to the version of \SAGE that you used

Fixed in the newest patch.

Great. The new revised patch 1389-tut.patch looks good to me.

[mvngu]

Replying to jhpalmieri:

Produced using hg_scripts: 1389-scripts.patch. This one hasn't been reviewed yet; the others all seem to have positive reviews.

The patch 1389-scripts.patch looks good to me. However, when I applied 1389-scripts.patch against sage-3.1.4 using the command hg_scripts.patch("<path-to>/1389-scripts.patch"), the following section from the patch was rejected:

diff -r 76339a4ccc14 -r f9dd774a1f61 sage-banner
--- a/sage-banner	Thu Oct 16 03:43:22 2008 -0700
+++ b/sage-banner	Mon Oct 20 16:36:06 2008 -0700
@@ -1,4 +1,4 @@
 ----------------------------------------------------------------------
-| SAGE Version 3.1.4, Release Date: 2008-10-16                       |
+| Sage Version 3.1.4, Release Date: 2008-10-16                       |
 | Type notebook() for the GUI, and license() for information.        |
 ----------------------------------------------------------------------

It seems that the script

sage-3.1.4/local/bin/sage-banner

that's shipped with sage-3.1.4 contains the line

SAGE Version 3.1.4, Release Date: 2008-10-20

and NOT

SAGE Version 3.1.4, Release Date: 2008-10-16

Notice the different release dates, which I think accounts for the said rejection. By the way, I fetched the sage-3.1.4 source distribution from

http://freethemes.mirror.aarnet.edu.au/pub/sage/src/sage-3.1.4.tar

So if we're going to fix the citation of Sage in the script sage-3.1.4/local/bin/sage-banner, then assuming you're working with sage-3.1.4, here's a suggestion:

-| SAGE Version 3.1.4, Release Date: 2008-10-20                       |
+| Sage Version 3.1.4, Release Date: 2008-10-20                       |

[mabshoff]

I can deal with the sage-banner issue.

Cheers,

Michael

[mvngu]

Change "SAGE" to "Sage" in sage-3.1.4/devel/sage-main/sage/misc/all.py.

[mvngu]

Change "SAGE" to "Sage" in sage-3.1.4/devel/sage-main/sage/misc/misc.py

[mvngu]

For the patches 1389-all.py.patch and 1389-misc.py.patch, please also see #4368. The patch trac_4368.patch from #4368 also deals with the same files that 1389-all.py.patch and 1389-misc.py.patch are dealing with.

[mabshoff]

Positive review for 1389-misc.py.patch.

Please do not add patches over and over again to this already very messy ticket. The SAGE -> Sage transformation has *zero* to do with the original ticket, so please add new tickets for additional patches.

Cheers,

Michael

[mabshoff]

1389-misc.py.patch and 1389-misc.patch also attempt to do the same thing. This is getting really messy.

Cheers,

Michael

[mvngu]

Replying to mabshoff:

1389-misc.py.patch and 1389-misc.patch also attempt to do the same thing. This is getting really messy.

Argh... sorry. My bad. In the future, I'd create new tickets to deal with the ongoing issue of SAGE -> Sage transformation.

[mabshoff]

Mike: 1389-tut.patch touches tut.tex.

Cheers,

Michael

[mabshoff]

Merged in Sage 3.2.alpha1

[mabshoff]

Replying to mvngu:

Argh... sorry. My bad. In the future, I'd create new tickets to deal with the ongoing issue of SAGE -> Sage transformation.

No problem. If possible make one ticket and attach a whole set of common changes, i.e. don't make one ticket per patch, but one ticket per group of files for example.

Thanks for your hard work.

Cheers,

Michael