Sage Tutorial

[Mike OS]

Months ago we posted a first draft of a Sage tutorial, written mainly
by David Monarres, with some from me and with support from San Diego
State University.
We now have it in much better from, using reStructured Text.

There are four parts to the tutorial: “How to use this tutorial” has
basic instructions about using and amending the tutorial, and the
others have mathematical content. “Sage as a Calculator” is intended,
as the title suggests, to cover straightforward computations, plotting
graphs, and content that one might find in a high school algebra
course, introductory statistics or calculus. We intend it to be
accessible to an entering college student, or to a bright high school
student.

“Programming in Sage” eases the transition to higher level mathematics
by treating topics that relate to the interface between mathematical
concepts and computational issues. This chapter covers basic
structures like: lists, sets and strings; the universe for a number or
variable, rational numbers versus real numbers; programming essentials
like booleans, conditionals and iterative computation; file handling
and data handling; etc.

“Mathematical Structures” is written at a more sophisticated level
than the earlier material, since the intended audience is college
students taking upper division math courses. The emphasis is on
learning about specific mathematical structures that have a Sage class
associated to them.

The final part is still rough in places, but we hope to work on it
this month. We'd love to have comments, contributions etc. License
is Creative Commons Attribution-Share Alike 3.0

Mike

[Mike OS]

Duh.

http://www-rohan.sdsu.edu/~mosulliv/Courses/sdsu-sage-tutorial/about.html

I'll find a better home for it later.

[David Joyner]

This looks excellent, IMHO. My only suggestion would be to replace italicized
"Sage as a Calculator" by actualy links to subsections.

Have you thought about making the 1st paragraph in the "About.." section
slightly more detailed? You could explain the "Helpful Tips" subsection very
briefly, for example (or you could add a sentence or two before the
"How to use this tutorial")?

> --
> You received this message because you are subscribed to the Google Groups "sage-edu" group.
> To post to this group, send email to sage...@googlegroups.com.
> To unsubscribe from this group, send email to sage-edu+u...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/sage-edu?hl=en.
>
>

[D.C. Ernst]

On Aug 7, 6:04 pm, Mike OS <mosul...@math.sdsu.edu> wrote:

> http://www-rohan.sdsu.edu/~mosulliv/Courses/sdsu-sage-tutorial/about....

This looks great! There are a few spots with typeset mathematics
(e.g., a=56) that look pretty awful on my screen because they are
shifted down half of a line. Could you incorporate MathJax for the
mathematics typesetting?

Dana

[v_...@ukr.net]

Hello!

On Sun, 7 Aug 2011 15:01:51 -0700 (PDT)
Mike OS <mosu...@math.sdsu.edu> wrote:

> Months ago we posted a first draft of a Sage tutorial, written mainly
> by David Monarres, with some from me and with support from San Diego
> State University.
> We now have it in much better from, using reStructured Text.
>

The Tutorial looks very nice and pretty extensive, which is very
good. :)
Have you thought of translating it into other languages already? I
mean not "performing the actual translation", but "preparing the
project for future translation". As far as I know, one of the problems
is to maintain the translations in the actual state so that upgrading
the English version was followed by the upgrading of the translations'
versions.
I believe translating the documentation into different languages is
extremely important. That is why I would like to participate in
the preparation of a Russian translation.

Regards,
Vladimir

-----
<v_...@ukr.net>

[David Monarres]

Hello all,

Sorry for not replying right away. I was on holiday over the weekend and intentionally took myself 'off the grid'.


Thank you for all of the comments, that is why we posted. Hopefully they keep coming!


Vladimir:


While we haven't done any work toward internationalization yet, one of the main reasons why we ditched our original back end for sphinx+restructured text was so that standard conversions would be easier to do. A quick look over the sphinx documentation shows that you can handle translation using gettext. I don't know if this is what the standard documentation uses, but I will begin the process of exposing that functionality to anybody who wants to translate and post back to the list with my progress.


D.C. Ernst:


We have not looked into the use of MatJax for equation rendering and I will admit that the png rendered equations aren't very aesthetically pleasing. We choose this because it was the quickest and easiest way to get cross-platform mathematics to display correctly using the limited web space that we had. We will look into other options.

David Joyner:

When you say that you would want the "Sage a a Calculator" section header to be replaced with links to the subsections. Do you mean just on the opening page? I am not clear on exactly what you are talking about, but if something is confusing about the navigation than we definitely want to change it. We mostly stuck with the default menu that sphinx provides and Sage documention already uses. 

Once again, thanks for all of the questions and suggestions. Hope that more are coming as people read more of it. 

Regards, 

David Monarres

[Jason Grout]

On 8/9/11 3:46 PM, David Monarres wrote:
> Thank you for all of the comments, that is why we posted. Hopefully they
> keep coming!

This looks fantastic! I love it!

Here are few typos for a random section that I looked at.

In
http://www-rohan.sdsu.edu/~mosulliv/Courses/sdsu-sage-tutorial/mathstruct.html#matrix-manipulation

* "we use the rows() and column() methods.": column() -> columns()

* "we use the singlular with the number row": singlular -> singular

* "zero.:" -> zero.:: -> zero. ::

Is there any chance you guys could post this up on google code,
bitbucket, or github (github being my preference)? I would have just
submitted pull requests for the typos above if it was convenient for me
to fork and change the source files.

As for MathJax (or jsmath), IIRC, recent versions of sphinx make it so
that you just have to include the jsmath (or mathjax) plugins instead of
the pngmath plugin.

Thanks,

Jason

[D. M. Monarres]

I will get on those typos right away.

Mike didn't include it in the original post but the code is up on bit
bucket already.

You can clone the source with the following command.

$ hg clone https://bitbucket.org/ayeq123/sdsu-sage-tutorial

or just go to https://bitbucket.org/ayeq123/sdsu-sage-tutorial and
click "get source"

Regards,

David M. Monarres
<dmmon...@gmail.com>

[D. M. Monarres]

Typos fixed and reading further about internationalization I am
surprised to find that internationalization was only added in sphinx
1.1. We would like for the docs to build with the sphinx included with
Sage, so that anybody who has Sage can contribute. Does anybody know
how the Sage project itself handles translation of docs? Were
translations just being done as individual projects?

Regards,

David M. Monarres
<dmmon...@gmail.com>

[Theron Hitchman]

As a newcomer to Sage, let me compliment you. I am on "vacation" but couldn't resist reading a little to see how it comes off. 

This is very clear and I think other new users would like it. When I have students who want or need to learn Sage, I will have them start with this tutorial.

TJ

[David Monarres]

So the facilities to use gettext to integrate the translations is new in Sphinx 1.1. But it looks rather easy to get it started, the basic outline is here http://sphinx.pocoo.org/latest/intl.html

[David Monarres]

Here is a version that uses mathjax. I agree that the output is very nice. Problem is that we cannot get the source to compile with that option using the sphinx that comes with Sage so I don't think that we will officially be using mathjax yet. 

http://www-rohan.sdsu.edu/~monarres/tutorial/

[v_...@ukr.net]

Hello!

On Tue, 9 Aug 2011 13:46:14 -0700 (PDT)
David Monarres <dmmon...@gmail.com> wrote:

>
> While we haven't done any work toward internationalization yet, one
> of the main reasons why we ditched our original back end for sphinx
> +restructured text was so that standard conversions would be easier
> to do. A quick look over the sphinx documentation shows that you can
> handle translation using gettext. I don't know if this is what the
> standard documentation uses, but I will begin the process of exposing
> that functionality to anybody who wants to translate and post back to
> the list with my progress.
>

It's not a problem to edit even the *.rst files as they are. The main
problem I can see is keeping the translation up-to date.

Regards,
Vladimir

-----
<v_...@ukr.net>

[Alex Ghitza]

This looks quite good. I noticed a small inconsistency in the section
about tab completion: "Since factorial looks like the correct command
to factor an integer we will select this by typing the next letter, i,
and hitting the tab key again." Factorial is of course *not* the
correct command to factor an integer...

Best,
Alex

--
Alex Ghitza -- Lecturer in Mathematics -- The University of Melbourne
-- http://aghitza.org

[David Monarres]

Thank you Alex. That is the exact sort of issue that I miss when I am staring at the same document for an hour or so. The more eyes the better!

The changes to the source are uploaded to bitbucket and a live updated version is at:

http://www-rohan.sdsu.edu/~monarres/tutorial/

Mike uploaded the tutorial to his webspace since my account may be deleted soon since I graduated. 

David

[David Monarres]

Alex,

Yes, that is a problem and unfortunately I don't know of an elegant way to solve it. On bitbucket, you can see logs and diffs for each change we make which should help you keep the translation up to date, other than that I am stumped. 

 I am excited by the idea of having the tutorial translated and will help out with whatever you think that you need to. 

David

[Mike OS]

Hi Vladimir

We now have a version that, although incomplete, is ready for
further development.  Please let me know if you are still interested
in translating it, and whether you need anything from our end.

Mike