Dear Dan, Jason, Minh, Sage devs,
Please find below a discussion on the appropriate location for tutorials.
On Fri, Mar 05, 2010 at 07:12:29AM -0800, bump wrote:
> > One question is where should we put those tutorials. During sage days 20, we
> > had lost of newcommers to Sage so we started to write several tutorials. We
>
> Are those tutorials available somewhere now?
With the Sage-Combinat patches applied, see:
doc/en/talks/sage-combinat-demo.rst
doc/en/talks/demo-iterator.py
doc/en/demo-NDPF.rst
Note that it is very much work in progress.
> > discussed a little about where those tutorial should ends into
> > sage. One of the main point was that putting them outside sage
> > sources make then unaccessible from the command line and ?
>
> Of course the documentation in the source files is essential. But
> although there is adequate documentation in the source files for
> someone who knows it is there and wants to dig, you don't get any
> sense of how to use the program from the reference manual.
>
> I think that for Lie group computations, Sage now has adequate tools
> for all the typical problems. (If there are gaps, let us fill them.)
> But people don't seem to know this. So I wanted to write a
> tutorial. A tutorial has a different function from the documentation
> in the source files and should be complementary.
Yes, yes, yes! We are all for it. Your work on the Lie tutorial is a
great addition to Sage's documentation. And +1 also for a good and
well advertised index of those tutorials like Minh is preparing.
Florent's point (and mine) though is that we would rather have those
tutorials live *within* the Sage sources, rather than in separate
directories / documents. The rationale is that this makes them
directly accessible through the online/introspection help, which is a
highly desirable feature. Try, e.g.:
sage: sage.categories?
sage: sage.categories.primer?
sage: sage.combinat?
sage: sage.combinat.root_system?
In particular, the above mentioned tutorials should probably be
accessible from:
sage: sage.combinat.tutorial?
sage: sage.combinat.tutorial_iterators?
This will be particularly powerful once the notebook inline help will
include a link to the corresponding live documentation (see
http://groups.google.com/group/sage-devel/msg/670d3392c3b6743f; I need
to create a ticket for this).
Another nice feature is that this keeps physically close all the
material on a given theme. Hence, someone browsing trough the combinat
sources will stumble on the combinatorics tutorial. Also, running:
sage -t sage/combinat
does check the combinatorics tutorial.
To summarize, and as was previously vaguely discussed on
http://groups.google.com/group/sage-combinat-devel/msg/18c3926662cf5033,
we would love to aim progressively at:
sage: sage? # quickref and short index for Sage
sage: sage.tutorial? # A short Sage tutorial + Minh's index
of thematic tutorials
sage: sage.groups # quickref and short index about group
theory
sage: sage.groups.primer?
sage: sage.groups.tutorial? # The main group theory tutorial +
links to other group theory tutorials
sage: sage.combinat.crystals? # quickref and short index about
crystals
By the way, Jason: can you remind me what's the difference between
'primer' and 'tutorial'? I remember one was meant to be doable in a
couple minutes, and the other in, say, half an hour, but can't recall
which is which.
That being said, it might be a bit tricky to find a natural spot for
cross-themes tutorials like Dan's. Should it be accessible through:
sage: sage.tutorial_lie?
Best regards,
Nicolas
--
Nicolas M. Thiéry "Isil" <nthi...@users.sf.net>
http://Nicolas.Thiery.name/
--
You received this message because you are subscribed to the Google Groups
"sage-combinat-devel" group.
To post to this group, send email to sage-combinat-de...@googlegroups.com.
To unsubscribe from this group, send email to
sage-combinat-devel+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/sage-combinat-devel?hl=en.
