On Nov 13, 2009, at 9:53 PM, Alex Ghitza wrote: > Hi, > > Martin Albrecht pointed out to me that there is a way to markup > citations and references in ReST (and that I should be using that in > my patches). I was so happy to see this that I immediately fixed my > patch and added a few words to the developer guide to this effect (see > http://trac.sagemath.org/sage_trac/ticket/7456 for this). > > It would seem that it's a fairly simple habit to get into: instead of > > def do_this(): > """ > Return really great thing, based on [ABC]. > > REFERENCES: > > - [ABC] The ABC of great things > > """ > > you would write > > def do_this(): > """ > Return really great thing, based on [ABC]_. > > REFERENCES: > > .. [ABC] The ABC of great things > > """ > > However, there are some issues in doing this on the large scale that > is the Sage library. > > 1. These references used to be local to the docstring they appear in. > As soon as we ReST-ify them, they become global in the reference > manual. Therefore if there is already a reference labeled [ABC], > Sphinx will rightfully complain. That's easy to fix, just use a > different label. > > 2. What happens if we cite the same reference from two different > docstrings? We have to pick which one docstring will contain the > "definition" of the reference, otherwise Sphinx will complain about > duplicates. The effect of this is: > > a) in the html output, the citation itself is a link to the reference, > so it's easy to get to it > > b) in the pdf output, all the references are *only* listed in the > bibliography section toward the end of the document. This means that > there are a bunch of lines that just say "REFERENCES" and nothing else > in the docstrings. Not very useful or pretty, so it would be great if > we could somehow remove them. > > c) in the docstring itself (obtained by introspection or by reading > the code directly), the citation will be there saying "see [ABC]" but > the actual reference could be nontrivial to find. In fact, the only > way to find it that's sure to work is to do search_src(".. [ABC]"), > because the definition could be in a different file, for instance. > > > I'm not sure I like c), but maybe that's the price that we have to pay > for having beautiful and consistent-looking documentation?
This is one of the many, many cases where I think it would be easier to fix the tool rather than change people's behavior. Why not have our cake and eat it too? [ABC] can automatically be turned into [ABC]_ (perhaps only if it matches something below). Global name conflicts can automatically be resolved, either by picking the first (if they're "close enough") or making them unique. The REFERENCES section can be stripped if its empty. I reallly like ReST, and it's a huge step ahead of what we used to have, but (and I've said this before) in many ways using raw ReST seems like a step backwards (double ::'s for doctests, ` for math mode, double-spacing function argument specs, etc.) - Robert --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
