Hey everyone, Two things on that note, I looked over the conventions page and noticed some discrepancies, which is now ticket http://trac.sagemath.org/sage_trac/ticket/13791 and I'd appreciate review. Second, Andrea, there are many bugs which are not mathematical problems, but errors in code/documentation, such as corner cases not checked or not robust enough (#11506, #12871, #9129, there are many others).
Best, Travis On Sunday, December 2, 2012 10:22:44 AM UTC-8, Volker Braun wrote: > > Your starting point should be the developer guide ( > http://www.sagemath.org/doc/developer), not the reference manual. The > latter is really for reference. I think the developer manual has a > reasonable explanation of the coercion model. A similar treatment of the > category framework is sorely lacking, I agree. It would be really great if > one of the people who was involved in writing it would step forward and add > a similar section to the developer guide. > > To further flesh out the developer guide, maybe we should include a > careful selection of module docstrings? By that I mean only the first > docstring in the module, ignoring all the class/function specific > docstrings. Some module docstrings are really written to give a high-level > overview and by cherry-picking those. I'm not sure if sphinx lets us > currently do that, though. > > > > On Sunday, December 2, 2012 12:43:49 PM UTC-5, Charles Bouillaguet wrote: >> >> Actually, I think I agree with the request of WM Chung. I found myself >> longing for a high-level overview of SAGE development. I think it >> could be pretty simple, but that it could explain how some things are >> organized. For instance : >> >> *) what is the category framework? what purpose does it serve? How >> should it (in theory) interact with the rest of the code? >> >> *) What is the rationale behind the class hierarchy? (mathematical >> sub-concept?) >> >> *) A pointer to the document somewhere that explains the >> coercion/conversion framework. >> >> >> And now, for something completely different. >> >> I think that the reference manual is very useful, but its linear >> structure (a loooooong list of items where it is not obvious where to >> find what you are looking for) is a bit baffling for beginners. I come >> from the MAGMA community, and I tend to think that the hierarchical >> structure of the MAGMA reference manual is a bit easier to navigate >> (http://magma.maths.usyd.edu.au/magma/handbook/). I could try to >> propose a patch implementing such a structure if someone thinks its >> worth it... >> >> Also, the presence of the category framework in the reference manual >> is also a bit confusing. For instance, when I was new to SAGE, I >> wanted to write something that manipulated vector spaces. I thus >> browsed the reference manual, and naturally found the "Vector Space" >> category... where, of course, I could not find the functions I was >> looking for. Why not remove the categories from the reference manual? >> What purpose do they serve? >> >> -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. Visit this group at http://groups.google.com/group/sage-devel?hl=en.
