On Aug 18, 2008, at 4:41 PM, John H Palmieri wrote: > On Aug 18, 2:02 am, Martin Albrecht <[EMAIL PROTECTED]> > wrote: >> On Monday 18 August 2008, John H Palmieri wrote: >> >>> I've been thinking about editing the Sage Programming Guide, and I >>> have many questions. >> >> Great! The survey showed that good developer docs is one of our main >> weaknesses.
Thanks for doing this! The Sage Programming Guide is horribly out of date. >> >>> According to the page <http://sagemath.org/doc/prog/node8.html>, >>> every >>> function is supposed to have an AUTHORS block. Is this really >>> right, >>> or is it okay to only have an AUTHORS block at the top of the file? >> >> I assume it is correct that each function is supposed to have such >> a block. In >> practice. If one particular set of authors wrote that file then >> maybe one can >> get away with only an AUTHORs block in the file. One nice thing >> about an >> AUTHOR block in each docstring: It is immediately clear whom to >> approach >> about a certain function. I vote for leaving this comment in. I think putting an AUTHORS block at the top of a file should be sufficient. >>> What's the status, accuracy-wise, of the coercion section <http:// >>> sagemath.org/doc/prog/node17.html>, given the new coercion code? >> >> That looks pretty outdated. >> Yes, that's pretty old. Craig Citro volunteered to write something up as part of his referee of the coercion changes (and we'd get to see how close his understanding of they system matched to my intent...) which would be a good starting point. This is something that I'd like to have much better documented, but my focus so far has been improving the documentation of the coercion code with examples and introspection capabilities. >>> The page <http://sagemath.org/doc/prog/node21.html> is called >>> "Creating a Sage Module or Package". What's the difference? In python terms, a module is a single .py file. A package is a directory full of .py files with an __init__.py. It should probably be renamed to something like "adding to the sage library." >>> In the same page, it says (after saying you can use C++, Cython, >>> etc. >>> for coding parts of your wonderful new package), "For readability >>> and >>> usability it is best to use Sage when possible." What does it >>> mean to >>> "use Sage"? Would it be better to say "use Python"? >> ??? I think the intent was that it's better to not use the Python/C API directly for readability's sake. >>> A few pages later <http://sagemath.org/doc/prog/node24.html>, it >>> says >>> that once you have a new package, you can "Send a copy to the sage- >>> devel Google group so it can be posted to the Sage web site, so >>> anybody can automatically install it by typing sage -i my_package- >>> version.spkg." Is this really right, or should it be submitted >>> to the >>> trac server and await refereeing? >> >> Yes, possibly one could add that a mail to [sage-devel] could help >> to raise >> awareness. > >> >> Generally speaking, the text is really old in real and in Sage >> time and thus >> many things are outdated. >> >> Other notes/my five cents: >> - Do we want a Cython manual in the development guide or should >> we link to >> the Cython docs? I don't know how comprehensive they are but if in >> doubt some >> of the material could be migrated over. Same for C++ which should be >> discussed in the Cython docs > > I think a link might be good enough, since the available Cython > documentation is more mature (and more substantial) now than it > probably was when the programming guide was written. I think there should be at least a page or so, with a pointer to the Cython documentation (which, admittedly, could be greatly improved). > >> - I think the refereeing process should be mentioned prominently. > > That's a good idea. Yes, I think this is a very important point. > - Robert --~--~---------~--~----~------------~-------~--~----~ To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/sage-devel URLs: http://www.sagemath.org -~----------~----~----~----~------~----~------~--~---
