2009/1/13 Alan G Isaac <aisaac@american.edu>:
There really is no substitute for using real cite keys and a central database of citations.
On 1/13/2009 9:44 AM Stéfan van der Walt apparently wrote:
How do you propose getting the citations into the docstrings? Each docstring needs a copy of its references, and those references may be to specific pages. I don't recall ReST supporting the LaTeX "[key, p. 13--40]" syntax. So, there's some work to be done. Come forward with either an implementation or a solid technical proposal, and I'll gladly take it further.
Originally I was just pointing out a problem. Proposing a good solution requires some discussion. The problem has also changed because of a suggestion that the docs should be usable for book compilation, and I am very uncertain how that is conceived. The key question is: should each docstring actually contain its citation, or can their be a page of citations? What I can offer to help with is this: automatic generation of citation keys, and automatic formatting of citations. This could be used to assist docstring authors. With no data base, this means that if you write a front end to accept citation info, we can spit out reST formatted citations plus a rule-based cite key. If the bib info is added to a data base, it could be a unique rule-based cite key. But really, all I originally wanted to do is call for an end to the uninformative use of reST footnotes in the place of reST citations with informative cite keys. fwiw, Alan Isaac PS You can always write [last-2009-sja]_, p.9. But you are right that reST does not allow "extra" info in the brackets with the cite key. More generally, it does not provide for treating the cite key as substitutable in generated documents. This is a big difference from LaTeX, but recall in reST the source is meant to be a human readable document. (Still, I'd like to see this functionality added.)