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 <[email protected]> wrote: > Hi Dan, > > On Sat, Mar 6, 2010 at 2:12 AM, bump <[email protected]> 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? > > [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 -- To post to this group, send an email to [email protected] To unsubscribe from this group, send an email to [email protected] For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
