nthiery
commented
11 years ago comment:1
Sébastien: can you have a look at the main index page? We had discussed it together last time I was in Montreal.
Closed nthiery closed 11 years ago
nthiery
commented
11 years ago Sébastien: can you have a look at the main index page? We had discussed it together last time I was in Montreal.
jhpalmieri
commented
11 years ago I think that intersphinx linking to the reference manual should be fixed by #6495. See also a sage-support thread.
jhpalmieri
commented
11 years ago By the way, was the sandpile document removed from the top-level index file intentionally?
nthiery
commented
11 years ago Description changed:
---
+++
@@ -20,6 +20,5 @@
The two first tutorials have been reviewed in depth by Samuel Lelièvre
during the Sage days in Bobo Dioulasso.
-Note: intersphinx linking to the reference manual is currently broken.
-I am about to create a ticket about this.
-
+Note: intersphinx linking to the reference manual is currently broken; see #14091.
+The thematic tutorial page look a bit lame without it, but I would not wait until #14091.Replying to @jhpalmieri:
By the way, was the
sandpiledocument removed from the top-level index file intentionally?
Ouch, thanks for catching this. The sandpile document should definitely be there. Where would you put it? In the combinatorics section maybe?
Cheers, Nicolas
nthiery
commented
11 years ago Replying to @jhpalmieri:
I think that intersphinx linking to the reference manual should be fixed by #6495. See also a sage-support thread.
That would be excellent news to have this feature back shortly! (not counting on the exciting parallel feature!
Nicolas
seblabbe
commented
11 years ago Attachment: Image 27.png
seblabbe
commented
11 years ago Replying to @nthiery:
Sébastien: can you have a look at the main index page? We had discussed it together last time I was in Montreal.
Yes, I remember vaguely but I can't remember exactly... Maybe, it was a bigger patch no? with more sections? Anyway, I looked at it and I think the sections and their order are fine.
However, some links do not appear as links (see attached png).
Also, links to PREP tutorials do not work.
seblabbe
commented
11 years ago I get the following 16 warning when building the html :
sage -docbuild thematic_tutorials html
....
reading sources... [ 95%] tutorial-objects-and-classes
reading sources... [100%] tutorial-programming-python
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-programm
ing-python.rst:390: WARNING: Literal block expected; none found.
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-programm
ing-python.rst:788: WARNING: image file not readable: media/graph0.png
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tut
orials/functional_programming.rst:: WARNING: document isn't included in any toctree
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/group_theory.rst:
: WARNING: document isn't included in any toctree
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/lie.rst:: WARNING
: document isn't included in any toctree
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/linear_programmin
g.rst:: WARNING: document isn't included in any toctree
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/numtheory_rsa.rst
:: WARNING: document isn't included in any toctree
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/sandpile.rst:: WA
RNING: document isn't included in any toctree
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-comprehe
nsions.rst:: WARNING: document isn't included in any toctree
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-notebook
-and-help-long.rst:: WARNING: document isn't included in any toctree
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-objects-
and-classes.rst:: WARNING: document isn't included in any toctree
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-programm
ing-python.rst:: WARNING: document isn't included in any toctree
...
writing output... [100%] tutorial-programming-python
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/index.rst:52: WAR
NING: undefined label: sage.rings.padics.tutorial (if the link has no caption the label must pre
cede a section header)
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/index.rst:60: WAR
NING: undefined label: sage.combinat.tutorial (if the link has no caption the label must precede
a section header)
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/index.rst:88: WAR
NING: undefined label: sage.categories.primer (if the link has no caption the label must precede
a section header)
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/index.rst:89: WAR
NING: undefined label: sage.categories.tutorial (if the link has no caption the label must prece
de a section header)
writing additional files... genindex search
copying images... [ 2%] media/sandpile/btw.png
...
build succeeded, 16 warnings.
Build finished. The built documents can be found in /Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/output/html/en/thematic_tutorials
Hi Sébastien!
Replying to @seblabbe:
I get the following 16 warning when building the html:
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-programm
ing-python.rst:390: WARNING: Literal block expected; none found.
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-programm
ing-python.rst:788: WARNING: image file not readable: media/graph0.pngThanks! This is fixed in the updated patch. I also fixed the missing links to sandpile tutorial (and some others as well!) and the section tree for the programming Python tutorial, where I did some further minor improvements.
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/index.rst:52: WAR
NING: undefined label: sage.rings.padics.tutorial (if the link has no caption the label must pre
cede a section header)
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/index.rst:60: WAR
NING: undefined label: sage.combinat.tutorial (if the link has no caption the label must precede
a section header)
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/index.rst:88: WAR
NING: undefined label: sage.categories.primer (if the link has no caption the label must precede
a section header)
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/index.rst:89: WAR
NING: undefined label: sage.categories.tutorial (if the link has no caption the label must prece
de a section header)
writing additional files... genindex search
copying images... [ 2%] media/sandpile/btw.pngYes. That's what #14091 is about (links to the reference manual). My opinion is that we should ignore them, especially since this should be fixed shortly by #6495.
checking consistency... /Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/functional_programming.rst:: WARNING: document isn't included in any toctree
...
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-programming-python.rst:: WARNING: document isn't included in any toctreeYes, I am not sure how to handle this. The toctree approach is not well suited here since we want the index to include a mix of references to local files and external files. I lamely silenced those warnings by adding a separate "toctree.rst" document which is just referenced from index.rst.
What do you think?
Cheers, Nicolas
nthiery
commented
11 years ago Replying to @seblabbe:
Yes, I remember vaguely but I can't remember exactly... Maybe, it was a bigger patch no? with more sections? Anyway, I looked at it and I think the sections and their order are fine.
Ok, thanks for checking!
- However, some links do not appear as links (see attached png).
Yup. That's #14091
- Also, links to PREP tutorials do not work.
They work in the live documentation ... The right thing to do would be
to put :ref...'s. John: do you know whether #6495 also enables links
from the thematic tutorials to the PREP's?
Cheers, Nicolas
nthiery
commented
11 years ago Description changed:
---
+++
@@ -12,13 +12,31 @@
tutorials that are already in the Sage sources (combinatorics, padics)
or other documents (PREP).
-Suggestions for a nicer way to link to the PREP documents are
-welcome. Shall we enable intersphinx there as well? Or should the
-PREP tutorial be simply merged in the thematic tutorials (is there a
-compelling reason to have separate documents?)
+A preview of the result is available here:
-The two first tutorials have been reviewed in depth by Samuel Lelièvre
-during the Sage days in Bobo Dioulasso.
+ http://combinat.sagemath.org/doc/thematic_tutorials/
-Note: intersphinx linking to the reference manual is currently broken; see #14091.
-The thematic tutorial page look a bit lame without it, but I would not wait until #14091.
+It might be slightly outdated w.r.t. the latest version of the
+patch. Also one should ignore the SEEALSO section which is added by a
+later patch in the Sage-Combinat queue.
+
+Status:
+
+- Sébastien and John checked the index page
+
+- The two first tutorials have been reviewed in depth by Samuel Lelièvre
+ during the Sage days in Bobo Dioulasso.
+
+- I proofread the last tutorial; but since I made changes, a last pass
+ of review would be needed.
+
+- Intersphinx linking to the reference manual is currently broken;
+ see #14091. The thematic tutorial page look a bit lame without it,
+ but I would not wait until #14091.
+
+- Suggestions for a nicer way to link to the PREP documents are
+ welcome. Shall we enable intersphinx there as well? Or should the
+ PREP tutorial be simply merged in the thematic tutorials (is there a
+ compelling reason to have separate documents?)
+
+Actually the link to the first PREP document was wrong. I just fixed that. In waiting for a better solution, the link seem to work in the static and the live documentation ...
nthiery
commented
11 years ago Reinstated the copyright notice I had inadvertently removed. Added proper patch header.
kcrisman
commented
11 years ago I like this a lot after only a few minutes of looking at it! What remains to be reviewed here? (I'm not sure whether most of it has positive review or not.)
And this does not depend on #6495, correct?
kcrisman
commented
11 years ago Here come some comments. First, generalities about the front page.
Or should the PREP tutorial be simply merged in the thematic tutorials (is there a compelling reason to have separate documents?)
Maybe not any more. At the time the thematic tutorials were pretty clearly thematic tutorials. Not really a lot of overlap between abelian sandpiles and an intro to doing calculus in Sage. In any case, one should keep existing links working.
Maybe that would be a next step - re-organizing all information in the Sage references. Currently there is also
Some of these things have been translated, which gives additional annoyance...
This is an index, grouped by theme, of Sage demonstrations, quick reference cards, primers, and thematic tutorials:I only see primers and thematic tutorials. Is this old language?
Also, what is the reason for the different formatting - there is italic, regular, bold, and even tt - on the front page?
With respect to the iteration tutorial, on request of nthiery höchstpersönlich! Mostly very minor English stuff.
You can use either of the following syntax:For example here sage: [i^2 if i%2 == 1 else 2 for i in range(10)]
[2, 1, 2, 9, 2, 25, 2, 49, 2, 81]The syntax has to be perfect. Does this work for ones with also for j in range(10) and so forth?
(hint:use srange() ...Iterators are build using parentheses:An iterators canYou can get the list of the results that are not yet consumed:What happens if you try to continue the iterator now? I think that would be useful to warn folks.
sage: it.next()
---------------------------------------------------------------------------
StopIteration Traceback (most recent call last)
StopIteration: give the same results; however the second timeit or something. Maybe untested.Using a list would be much slower here:# not tested!sage: for p in Partitions(): print p
sage: for p in Primes(): print pzip and friends. Or is that in a previous tutorial?Overall I like it, though!
kcrisman
commented
11 years ago Python tutorial:
range, probably you should at least make some mention of xrange, srange, sxrange, and friends and what they do. Edit: point to further down where you do.zip.kcrisman
commented
11 years ago Changed reviewer from Samuel Lelièvre, Sébastien Labbé to Samuel Lelièvre, Sébastien Labbé, Karl-Dieter Crisman
kcrisman
commented
11 years ago Front page:
The introductory tutorial:
Patchbot is giving this a green light, so I'd say fix the (mostly very minor) things I pointed out and you've got a nice upgrade to the Sage documentation on your hands!
nthiery
commented
11 years ago Hi Karl!
Thanks for the proofreading and suggestions!
Replying to @kcrisman:
Python tutorial:
- Dive into Python does still exist because of the license, but the author has essentially repudiated it. In any case, the link is broken.
Link fixed. It remains good stuff!
- "The elements of a set must be hashable:" - do these readers know what that means? Give an example of something that isn't.
I added a TODO at the end about those.
- "Todo Introduction to the debugger." To do?
This is just using the standard Sphinx markup .. TODO::
- With
range, probably you should at least make some mention ofxrange,srange,sxrange, and friends and what they do. Edit: point to further down where you do.
Done.
- I'm a little confused about the structure of this document. You have this big list of stuff, and then exercises, and then magically lots of explanation of the stuff (like control structures) you glossed over earlier. ??? There is some redundancy, I think.
Yeah, indeed. This stems from the fact that we usually run this tutorial by having someone gloss over the first part and then have the student work on their own on the rest.
- Again, I highly recommend pointing out
zip.
+1. It's mentionned later on.
- "That is, it cannot be changed once it is created." Maybe talk about why that might be useful.
Done.
Altogether, it could use some reorganisation and complements not perfect. However I would go for getting this in and improving it further in a later ticket! Ok with that?
nthiery
commented
11 years ago Replying to @kcrisman:
Front page:
- I figured out the different typefaces - it's the different types of links. Italics only for Sphinx links. I don't know whether this is worth fixing - after #6495 it should be easy. The :class: link probably should be different, though.
Agreed, this is ugly. But it's about style and not content. So yes, that should be for another ticket.
- I'm torn between putting the programming ones immediately after the intro ones or having them where they are. What do you think?
I just added a link from the intro to the programming tutorials.
- Modeling Mathematics - that could be very confusing. I'd use a word other than "modeling", as that means something very different to most people.
I see the potential confusion. Yet I am strongly attached to the word Modeling, because that's really what we are doing (in the sense of http://en.wikipedia.org/wiki/Object-oriented_modeling, though we don't necessarily have to use only object-oriented techniques). I changed the title to "Modeling Mathematics on a computer". Is this better?
- If you want to add even more things, please finish the review of the Quickstarts at #13381!
:-)
This sounds nice! I'll try to have a more detailed look! For now I'll focus on getting those in before they rot away.
The introductory tutorial:
"If you are browsing this document as a static web page, " - probably add something here that the active instructions assume that you are browsing it live. That's implicit, but explicit is better than implicit, according to Python…
"mathematics like this sin(x)−y3 by using dollar signs" - maybe one should have \sin or something? The "sin" shouldn't be italicized.
The \ is there in the .rst file.
- "Still, it is possible to define symbolic functions without first defining its variables:" - "their variables", maybe
- "colour it red" - I don't know whether US English is the Sage standard. If it is, make it "color" :-)
I think it is.
Patchbot is giving this a green light, so I'd say fix the (mostly very minor) things I pointed out and you've got a nice upgrade to the Sage documentation on your hands!
:-)
Thanks again for the review!
nthiery
commented
11 years ago Replying to @kcrisman:
Here come some comments. First, generalities about the front page.
Or should the PREP tutorial be simply merged in the thematic tutorials (is there a compelling reason to have separate documents?)
Maybe not any more. At the time the thematic tutorials were pretty clearly thematic tutorials. Not really a lot of overlap between abelian sandpiles and an intro to doing calculus in Sage.
Ok.
In any case, one should keep existing links working.
Definitely!
Maybe that would be a next step - re-organizing all information in the Sage references. Currently there is also
- Three Lectures about Explicit Methods in Number Theory Using Sage
- Numerical Sage
- A Tour of Sage
- Constructions
Some of these things have been translated, which gives additional annoyance...
Yup. Do you mind opening a ticket for this?
This is an index, grouped by theme, of Sage demonstrations, quick reference cards, primers, and thematic tutorials:I only see primers and thematic tutorials. Is this old language?
No it's new language :-) There are a bunch of demos in the Sage-Combinat queue. I commented it out for later.
With respect to the iteration tutorial, on request of nthiery höchstpersönlich! Mostly very minor English stuff.
- What is the plural of "syntax"? I would use "syntaxes" as a common variant.
I changed this to "idioms" :-)
- An extremely useful addition is
sage: [i^2 if i%2 == 1 else 2 for i in range(10)] [2, 1, 2, 9, 2, 25, 2, 49, 2, 81]
Added.
The syntax has to be perfect. Does this work for ones with also
for j in range(10)and so forth?
I am not sure what you mean here.
What happens if you try to continue the iterator now? I think that would be useful to warn folks.
Done!
- Show this with an example and
timeitor something. Maybe untested.Using a list would be much slower here:
Done.
- Make sure these are marked
# not tested!sage: for p in Partitions(): print p sage: for p in Primes(): print p
Better be indeed :-) Done!
- Finally, I think that something about iterables should mention
zipand friends. Or is that in a previous tutorial?
It is!
Overall I like it, though!
:-)
nthiery
commented
11 years ago Attachment: trac_14090-thematic_tutorials-nt.patch.gz
nthiery
commented
11 years ago Changed reviewer from Samuel Lelièvre, Sébastien Labbé, Karl-Dieter Crisman to Samuel Lelièvre, Sébastien Labbé, Karl-Dieter Crisman, Darij Grinberg
nthiery
commented
11 years ago Status: ready to go, assuming the patchbot goes green.
The two first tutorials have been reviewed in depth by Samuel Lelièvre during the Sage days in Bobo Dioulasso.
Sébastien, John, Karl checked the index page
I proofread the last tutorial
Karl and Darij reproofread all documents. I implemented all changes by Darij.
The link to the PREP document seem to work. Intersphinx linking would be nicer. But that is for later!
Thanks everybody!
nthiery
commented
11 years ago Description changed:
---
+++
@@ -20,23 +20,3 @@
patch. Also one should ignore the SEEALSO section which is added by a
later patch in the Sage-Combinat queue.
-Status:
-
-- Sébastien and John checked the index page
-
-- The two first tutorials have been reviewed in depth by Samuel Lelièvre
- during the Sage days in Bobo Dioulasso.
-
-- I proofread the last tutorial; but since I made changes, a last pass
- of review would be needed.
-
-- Intersphinx linking to the reference manual is currently broken;
- see #14091. The thematic tutorial page look a bit lame without it,
- but I would not wait until #14091.
-
-- Suggestions for a nicer way to link to the PREP documents are
- welcome. Shall we enable intersphinx there as well? Or should the
- PREP tutorial be simply merged in the thematic tutorials (is there a
- compelling reason to have separate documents?)
-
-I have a couple minor quibbles yet but not worth mentioning as they are to some extent stylistic.
HOWEVER I think you should ask Harald to reorganize the standard doc page in light of this, AND I think that somewhere in there is also the source for the Sage doc which should be reorganized in light of this. After all, that is where people will be going first, and these need to make it easy for people to get to the page organized here.
nthiery
commented
11 years ago Replying to @kcrisman:
I have a couple minor quibbles yet but not worth mentioning as they are to some extent stylistic.
Further work on those tutorials in a followup ticket is welcome :-)
HOWEVER I think you should ask Harald to reorganize the standard doc page in light of this, AND I think that somewhere in there is also the source for the Sage doc which should be reorganized in light of this. After all, that is where people will be going first, and these need to make it easy for people to get to the page organized here.
Yup. I just sent him an e-mail, and added him in CC.
I can't wait for the patchbot to actually run the tests ...
jdemeyer
commented
11 years ago Merged: sage-5.8.beta3
nthiery
commented
11 years ago Yippee!
Thanks everybody for the writing and review! That will be super handy to have all those tutorials right under hand during upcoming Sage days.
Cheers, Nicolas
jdemeyer
commented
11 years ago We don't support "et al." as Author
jdemeyer
commented
11 years ago Changed author from Franco Saliola, Florent Hivert, Nicolas M. Thiéry, et al. to Franco Saliola, Florent Hivert, Nicolas M. Thiéry
fchapoton
commented
9 years ago Description changed:
---
+++
@@ -14,7 +14,7 @@
A preview of the result is available here:
- http://combinat.sagemath.org/doc/thematic_tutorials/
+http://combinat.sagemath.org/doc/thematic_tutorials/
It might be slightly outdated w.r.t. the latest version of the
patch. Also one should ignore the SEEALSO section which is added by ayet another TAB removed in the desc field.
This ticket adds three tutorials that have been developped and extensively used during Sage(-Combinat) events:
There is some redundancy with the PREP's tutorial, but that's fine: the point of views are complementary.
At this occasion, this ticket also refactors the main Thematic Tutorials page, grouping them by theme, and cross-linking to thematic tutorials that are already in the Sage sources (combinatorics, padics) or other documents (PREP).
A preview of the result is available here:
http://combinat.sagemath.org/doc/thematic_tutorials/
It might be slightly outdated w.r.t. the latest version of the patch. Also one should ignore the SEEALSO section which is added by a later patch in the Sage-Combinat queue.
CC: @sagetrac-sage-combinat @seblabbe @novoselt @haraldschilly
Component: documentation
Keywords: thematic tutorials
Author: Franco Saliola, Florent Hivert, Nicolas M. Thiéry
Reviewer: Samuel Lelièvre, Sébastien Labbé, Karl-Dieter Crisman, Darij Grinberg
Merged: sage-5.8.beta3
Issue created by migration from https://trac.sagemath.org/ticket/14090