0 views

Skip to first unread message

Message has been deleted

Mar 5, 2010, 12:43:50 PM3/5/10

to sage-...@googlegroups.com

On Mar 5, 2010, at 9:08 AM, Minh Nguyen wrote:

> Hi Dan,

>

> On Sat, Mar 6, 2010 at 2:12 AM, bump <bu...@match.stanford.edu> wrote:

>

> <SNIP>

>

>> 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'm glad you brought this up. Your description above nicely sums up

> the purpose of a reference manual, and at the same time points out its

> drawbacks.

>

>

>> 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.

>

> I personally like the way the Python standard documentation [1] is

> organized. And I very much like the Sage standard documentation to

> adopt what works for end users and beginners. Another possible source

> of inspiration for improving the Sage documentation can be found in

> the Perl documentation [2]. As regards accessible documentation, I

> hold the Django documentation [3] in high esteem.

>

>

>> Probably Sage would benefit from an expanded set of good tutorials

>> here:

>>

>> http://www.sagemath.org/doc/

>>

>> To get the Lie tutorial into that page I guess I would edit

>>

>> devel/sage/doc/en/website/templates/index.html

>>

>> when the patch is revised.

>

> Before you do so, for the record, I would like to point out some ideas

> that have been in the documentation backlog for quite some time. A

> review of the current Sage documentation shows that it consists of the

> following:

>

> * Tutorial --- a tutorial guide to some of Sage's features that are

> useful for beginners.

>

> * Developer's Guide --- guidelines and policies regarding Sage

> development.

>

> * Constructions --- various short guides along the line of "How do

> I...?"

>

> * Reference Manual --- the Sage reference manual.

>

> * A Tour of Sage --- a very short guide along the line of

> Mathematica's tour.

>

> * Numerical Guide --- numerical computation with Sage.

>

> * Installation Guide --- how to install Sage.

>

> * Three Lectures about Explicit Methods in Number Theory Using Sage

> --- how to do computations in algebraic number theory, especially

> number fields and modular forms.

>

> What I'm proposing and offer for discussion (and am willing to devote

> time and energy to the effort) is this. Expand the Sage standard

> documentation to include the following:

>

> * Sage HOWTOs --- consisting of various in-depth documents on

> specific topics.

>

> * FAQs --- a collection of answers to frequently asked questions.

>

> The FAQs can incorporate the existing one on the Sage wiki [4], in

> addition to fleshing it out further.

>

> The category of Sage HOWTOs needs more thought. Some chapters in the

> Constructions Document [5] fit nicely within the category of HOWTOs,

> e.g.

>

> * Linear Programming

>

> * Python Functional Programming for Mathematicians

>

> But are not all of the chapters making up the Constructions Document

> written in the style of HOWTOs? I don't know how to answer this

> question myself. Anyway, if one is to include in-depth guides in the

> "Sage HOWTOs" classification, I would propose first including the

> following:

>

> * Python Functional Programming for Mathematicians

>

> * Sage and Coding Theory [6,7]

>

> * Sage and Cython: A Brief Introduction [8]

>

> * Linear Programming in Sage [9,10]

>

> * Group Theory and Sage: A Primer [11]

>

> * Sage and Cython: A Brief Introduction [12]

>

> * Number Theory and the RSA Public Key Cryptosystem [13]

>

> * Lie Methods and Related Combinatorics [14]

>

> I can't help but put the number 13 next to the number theory document

> because that document deals with prime numbers :-)

>

> I can see some advantages and disadvantages for introducing the two

> new classifications: FAQs, and Sage HOWTOs.

>

> Pros: All doctests in the above documents are regularly executed

> before each release. Having these HOWTOs and FAQs available with every

> Sage release means that one does not need to download them separately

> from various websites outside of the Sage infrastructure. For a binary

> distribution of Sage, all the standard documentation comes pre-built

> in HTML format. Another good thing (for the Sage website maintainers)

> is that the help and support page [15] would be less cluttered with

> miscellaneous documents.

>

> Cons: It would add some megabytes to the Sage source and binary

> distributions. Who is going to contribute time and effort to make this

> happen? I feel that I should not write such a long email if I'm not

> going to express my firm willingness to contribute to realizing the

> above proposals. As a first round of improvements that implements some

> of the above tasks, I'm willing to incorporate the FAQs into the

> standard documentation. I'm also willing to create the new category

> "Sage HOWTOs" and incorporate the following documents in it:

>

> * Python Functional Programming for Mathematicians

>

> * Number Theory and the RSA Public Key Cryptosystem [13]

>

> I wrote those two documents, so I'm more familiar with them than I am

> with the others. All I'm asking is that people contribute to the

> reviewing process.

>

> Thoughts?

The pros certainly seem to outweigh the cons for me.

- Robert

Mar 5, 2010, 5:25:34 PM3/5/10

to sage-...@googlegroups.com

Huge +1. I had decided long ago that I wanted something just like you

propose above, and I really hope it happens sooner rather than later.

The "testing" and "being available with Sage" pro's are really

*huge*. They are especially useful for users not on the internet.

By the way, if you look at the MATLAB distribution, it's about 3.3GB

and most of that is documentation (including videos!).

-- William

>

> The pros certainly seem to outweigh the cons for me.

>

> - Robert

>

>

> --

> To post to this group, send an email to sage-...@googlegroups.com

> To unsubscribe from this group, send an email to

> sage-devel+...@googlegroups.com

> For more options, visit this group at

> http://groups.google.com/group/sage-devel

> URL: http://www.sagemath.org

>

--

William Stein

Associate Professor of Mathematics

University of Washington

http://wstein.org

Mar 6, 2010, 12:11:18 PM3/6/10

to sage-devel

Minh,

I wonder how one can contribute changes/patches to files in sage/doc/

en/constructions

It's also not always clear who wrote what there, and thus seems hard

to discuss possible

improvements with authors.

Thanks,

Dima

On Mar 6, 1:08 am, Minh Nguyen <nguyenmi...@gmail.com> wrote:

> Hi Dan,

>

> * Python Functional Programming for Mathematicians

>

> But are not all of the chapters making up the Constructions Document

> written in the style of HOWTOs? I don't know how to answer this

> question myself. Anyway, if one is to include in-depth guides in the

> "Sage HOWTOs" classification, I would propose first including the

> following:

>

> * Python Functional Programming for Mathematicians

>

> * Sage and Coding Theory [6,7]

>

> * Sage and Cython: A Brief Introduction [8]

>

> * Linear Programming in Sage [9,10]

>

> * Group Theory and Sage: A Primer [11]

>

> * Sage and Cython: A Brief Introduction [12]

>

> * Number Theory and the RSA Public Key Cryptosystem [13]

>

> * Lie Methods and Related Combinatorics [14]

>

> I can't help but put the number 13 next to the number theory document

> because that document deals with prime numbers :-)

>

> I can see some advantages and disadvantages for introducing the two

> new classifications: FAQs, and Sage HOWTOs.

>

> Pros: All doctests in the above documents are regularly executed

> before each release. Having these HOWTOs and FAQs available with every

> Sage release means that one does not need to download them separately

> from various websites outside of the Sage infrastructure. For a binary

> distribution of Sage, all the standard documentation comes pre-built

> in HTML format. Another good thing (for the Sage website maintainers)

> is that the help and support page [15] would be less cluttered with

> miscellaneous documents.

>

> Cons: It would add some megabytes to the Sage source and binary

> distributions. Who is going to contribute time and effort to make this

> happen? I feel that I should not write such a long email if I'm not

> going to express my firm willingness to contribute to realizing the

> above proposals. As a first round of improvements that implements some

> of the above tasks, I'm willing to incorporate the FAQs into the

> standard documentation. I'm also willing to create the new category

> "Sage HOWTOs" and incorporate the following documents in it:

>

> * Python Functional Programming for Mathematicians

>

> * Number Theory and the RSA Public Key Cryptosystem [13]

>

> I wrote those two documents, so I'm more familiar with them than I am

> with the others. All I'm asking is that people contribute to the

> reviewing process.

>

> Thoughts?

>

> [1]http://docs.python.org

>

> [2]http://www.perl.org/docs.html

>

> [3]http://docs.djangoproject.com

>

> [4]http://wiki.sagemath.org/faq

>

> [5]http://www.sagemath.org/doc/constructions/

>

> [6]http://trac.sagemath.org/sage_trac/ticket/3624

>

> [7]http://sage.math.washington.edu/home/wdj/cookbook/coding-theory/sage-...

>

> [8]http://openwetware.org/wiki/Open_writing_projects/Sage_and_cython_a_b...

>

> [9]http://www-sop.inria.fr/members/Nathann.Cohen/tut/LP/

>

> [10]http://www.sagemath.org/doc/constructions/linear_programming.html

>

> [11]http://buzzard.ups.edu/sage/sage-group-theory-primer.pdf

>

> [12]http://openwetware.org/wiki/Open_writing_projects/Sage_and_cython_a_b...

>

> [13]http://sites.google.com/site/nguyenminh2/numtheory-crypto-sage.pdf

>

> [14]http://trac.sagemath.org/sage_trac/ticket/8442

>

> [15]http://www.sagemath.org/help.html

>

> --

> Regards

> Minh Van Nguyen

Message has been deleted

Mar 9, 2010, 3:44:21 AM3/9/10

to sage-comb...@googlegroups.com, sage-...@googlegroups.com

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.

> > 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" <nth...@users.sf.net>

http://Nicolas.Thiery.name/

Reply all

Reply to author

Forward

Message has been deleted

0 new messages

Search

Clear search

Close search

Google apps

Main menu