[Numpy-discussion] coding style: citations

[Stéfan van der Walt]

2009/1/12 Alan G Isaac <aisaac@american.edu>:
> This would really involve the following.
> Create a searchable database of citations
> and an interface for adding to it.
> Unique keys would be generated by your
> algorithm of choice when an entry is added.
> Authors would be asked to use only references
> in the database.
>
> Desirable for a book.  Desirable for documentation?

In documentation, you want the reference to appear in the docstring
itself.  Our docstrings double as the content of a book, which is why
it may be easier to extract the bibliography from the docstrings,
rather than populating the docstrings from a central bibliography.

> Numerical keys will clearly *not* be consistent.
> The same key will refer to different citations
> on different pages, and key width will not be
> uniform.

We automatically renumber the citations to take care of this.

> In additional, numerical keys are
> not informative when encountered by the reader.
> I would prefer [last1.last2-2009-sja]_ where
> sja is "standard journal abbreviation" and
> last names are ASCII (e.g., ø -> o).

I agree.

> But to answer your question, bibstuff includes
> biblabel.py, which can produce keys for a bibtex
> database (styled as you like).  The problem of
> setting up the data base remains.

We can add an interface to the documentation editor, where a person
pastes the BiBTeX reference, and it returns the appropriate key to use
in the docs.  Mabe you can think of a more intuitive interface, even.
As long as we have a consistent way of generating keys, I'd gladly use
them.

Regards
Stéfan