Hi Alan 2009/1/11 Alan G Isaac <aisaac@american.edu>:
The docstring standard at http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines#docstring-s... suggests a citation reference format that is not compatible with reStructuredText. Quoting from http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#citations:
Citations are identical to footnotes except that they use only non-numeric labels such as [note] or [GVR2001].
In other words, the standard currently promotes a conflation of notes and citations.
Thank you for your feedback. Yes, this is a problem. In a way, RestructuredText is partially to blame for not providing numerical citation markup. If we can come up with a good way of generating the reference keys, we can still change the current format. Maybe the library you mention below can automatically generate such keys? I'd like to take that responsibility away from documentation writers, since it is not always obvious how to generate consistent keys. Regards Stéfan
Another reason for avoiding the style currently in the docstring standard is that it renders impossible the generation of citations using a citation database. (See e.g. the bibtext-like facilities offered by bibstuff's bib4txt (http://code.google.com/p/bibstuff/).
Alan Isaac
_______________________________________________ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion