On Nov 14, 2:46 pm, Alex Ghitza <aghi...@gmail.com> wrote:
> On Sat, Nov 14, 2009 at 02:20:43PM -0800, John H Palmieri wrote:
>
> > In what way are they a total mess? I'm curious.
>
> > > Of course, it was inevitable that we would run head first into this
> > > problem eventually, and it's amusing that we did this week.
>
> > > Anyway, I agree with Robert -- to solve this particular problem we
> > > will have to go creatively beyond what Sphinx offers "out of the box".
>
> > Which particular problem? Alex just pointed out that we haven't been
> > using standard Sphinx/reST for citations, and we should. That's easy
> > to solve "in the box".
>
> Here's an example (I'm not picking on you, John, this was just the
> first instance I ran into this after doing search_src("REFERENCE") to
> look for un-Sphinx-ified references.)
The curse of alphabetical order and working on something in the
"algebras" directory, I suppose...
> In the module docstring of steenrod_algebra.py, there is a reference
> to Milnor's Annals paper [Mil]. I eagerly put this in proper Sphinx
> syntax. Moving on to steenrod_algebra_element.py, I had to remove the
> same reference from the module docstring because Sphinx complained.
> So you can have something like "see [Mil]_" but then the actual
> reference is nowhere to be found in that file.
> This means that someone reading only this docstring does not have this
> information at hand any more. Then we get to
> steenrod_algebra_bases.py, where the Monks and Wood papers are now [M]
> and [W], whereas in steenrod_algebra_element.py they were [Mon] and
> [Woo]. Sphinxify these and you get duplicate references
> with different names and labels.
Oops, sorry about that. See my response to William's message about a
possible solution.
> Once again, I'm not picking on you or anybody else.
It's fine. (I would feel worse if we had a policy about consistency
in references/citations which I had violated in those files.)
> But I think this
> shows that it's hard to keep consistency alive even in cases where a
> single author wrote a bunch of files, never mind what happens when ten
> different people work on the same code. It adds to the author's
> workload and to the reviewer's workload. And as we pointed out
> already, it cripples docstrings introspection.
Right, I completely agree with Robert and with you that we need
introspection to work right, with all of the references included
"locally".
John
--~--~---------~--~----~------------~-------~--~----~
To post to this group, send an email to sage-devel@googlegroups.com
To unsubscribe from this group, send an email to
sage-devel-unsubscr...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sage-devel
URL: http://www.sagemath.org
-~----------~----~----~----~------~----~------~--~---
