On Tue, Mar 09, 2010 at 09:57:31AM +1100, Minh Nguyen wrote:
> > 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
>
> Overall, the above is an excellent proposal for centralizing source
> code and documentation (reference manual, tutorials, primers). I can
> imagine that I would want to do
>
> sage: sage.groups.tutorial?
>
> to get a tutorial on how to use the group theory module. Also, to do
>
> sage: sage.groups.primer?
>
> to get a primer on the group theory module. That is, inline
> documentation available from the command line and through the notebook
> interface.
I am glad we are on the same line.
> In case this hasn't come up before, I want to now focus on how all
> these tutorials and primers are to be organized in the HTML version
> of the standard documentation [1]. Are they to be found in the
> Reference Manual [2]? Or within a thematic new category such as
> "Sage HOWTOs" as proposed at #8470 [3]?
My first thought would be to stuff everything in the reference manual
(in particular to encourage consistency and cross-references with the
rest of the reference manual), and have a separate, concise, and well
advertised index of all the thematic quickrefs/primer/tutorials
pointing to the appropriate sections of the reference manual. But my
editorial skills for large scale documentation management are close to
non existent. Jason Bandlow: you have a good view on this kind
of thing though; feedback welcome!
> Since you mentioned the phrase "thematic tutorials" above, I have an
> urge to borrow (no, steal :-) the phrase and instead rename "Sage
> HOWTOs" to "Thematic Tutorials". I really like that phrase of yours.
Please go ahead :-)
> > By the way, Jason: can you remind me what's the difference between
> > 'primer' and 'tutorial'?
>
> * primer --- a mini tutorial that should get you started, up and
> running in a few minutes.
>
> * tutorial --- requires about half an hour (or more) to work through.
Ok, thanks!
Cheers,
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.
