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.
>
> > First, what do you think about changing the name to the Sage
> > Developers' Guide, or something like that, since most of the document
> > has more to do with development issues than programming issues?
>
> I agree it sounds better and fits the purpose better. I'm all for it.
>
> > Specific questions:
>
> > According to this page <http://sagemath.org/doc/prog/node7.html>,
> > authors of Sage code are supposed to "share copyright with William
> > Stein". Is this accurate?
>
> No. There was a discussion about this at Sage Days 2 (October 2006) and we
> came to the conclusion that this is not what we want nor to share copyright
> with another entity like a Sage Foundation. Possibly the Programming Guide
> outdates this meeting.
>
> > 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.
>
> > 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.
>
>
>
> > In the mutability section <http://sagemath.org/doc/prog/node18.html>,
> > there is a comment saying "Rewrite. Difficult to parse. Make gentler",
> > and "Put a tutorial on this here". Anyone have specific ideas about
> > how to do this?
>
> > The page <http://sagemath.org/doc/prog/node21.html> is called
> > "Creating a Sage Module or Package". What's the difference?
>
> > 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"?
>
> > 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.
>
> > The page <http://sagemath.org/doc/prog/node29.html> on
> > testing .py, .pyx, and .sage files has an email to William about
> > doctesting and importing. Can someone suggest how to incorporate this
> > into the text?
>
> > For the Mercurial chapter: how important is the page <http://
> > sagemath.org/doc/prog/node73.html>, "Updating To the Latest Official
> > Sage Library Source Code"? Its references to kdiff3 are not
> > appropriate, among other things.
>
> This is also outdated. Back in the days, William would update the master
> repository between releases whereas nowadays that hardly happens. So it
> should probably replaced by some text about sage -upgrade. However, hg pull
> might still be mentioned w.r.t. private repositories?
>
> > The "Miscellaneous" chapter <http://sagemath.org/doc/prog/node74.html>
> > is a real mess. The first section is a transcript of an IRC chat; the
> > second section is called "Weird issues" and only discusses one thing;
> > and the third has no explanatory text at all. Any suggestions for
> > improvements?
>
> - I'd loose weird issues
> - I'd loose benchmarking (and/or write something else about that matter)
> - I suppose one should write a short note on circular imports and how to
> avoid them
Okay, I think I'll add it to the already existing section on importing
modules, and just call the section "Importing".
>
> 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 the refereeing process should be mentioned prominently.
That's a good idea.
> - Maybe a little tutorial on how to change something small and get it into
> Sage (including rebuilding, make test, Trac, reviews) would be nice?
I already have a draft of a section on the trac server, but a tutorial
like this makes sense, too.
> - the SPKG inclusion guidelines should probably also go into the Dev manual.
Where can I find these guidelines?
Thanks,
John
>
> Cheers,
> Martin
>
> --
> name: Martin Albrecht
> _pgp:http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x8EF0DC99
> _www:http://www.informatik.uni-bremen.de/~malb
> _jab: [EMAIL PROTECTED]
--~--~---------~--~----~------------~-------~--~----~
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
-~----------~----~----~----~------~----~------~--~---
