[Numpy-discussion] coding style: citations

[Alan G Isaac]

> 2009/1/13 Alan G Isaac <aisaac at 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.)