On Aug 18, 8:33 pm, Robert Bradshaw <[EMAIL PROTECTED]>
wrote:
> 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.
That's what I thought, but I'll still mention them as, at least some
of the time, being a good idea at the function-level, too. (Since
that was Martin's opinion.)
>
> >>> 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.
Good, I'm looking forward to seeing it.
> 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.
My current plan is to rewrite this part, getting rid of the phrase
"use Sage when possible", among other changes.
> >>> 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).
What I've seen at cython.org is much better than what is in the
Programming Guide, it seems to me (although since I haven't really
used Cython, I'm probably not the best judge). This is what I mean by
being more mature and more substantial now. In any case, I think we
should view Cython as being a separate project, with its own
documentation, and hence most of the burden for its documentation
should lie elsewhere.
> >> - I think the refereeing process should be mentioned prominently.
>
> > That's a good idea.
>
> Yes, I think this is a very important point.
The current structure in my new draft is like this:
Intro
conventions for coding (i.e., format for the headers of files,
docstrings, automated testing)
coding in Python (_latex_ and _repr_ methods, preparsing, coercion,
etc.)
coding in other languages (Cython, (maybe mention C++ interface),
interfaces to PARI, GAP, Singular)
Then the rest of the manual will deal with (in some order, which I'm
still thinking about):
Mercurial
the trac server, the refereeing process
tutorial on how to contribute bug fixes, new code, documentation
changes, etc.
John
> - 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
-~----------~----~----~----~------~----~------~--~---
