On 1/11/2009 4:13 PM Stéfan van der Walt apparently wrote:

Thank you for your feedback. Yes, this is a problem. In a way, RestructuredText is partially to blame for not providing numerical citation markup.

I do not agree. I cannot think of any bibliography tool that uses numerical citation reference keys. Naturally there are many that *substitute* numerical citation references for the cite key used by the author. This is a *style* question that should be automated (i.e., not be a responsibility of the author). E.g., LaTeX provides a variety of styles for cite key substitution.

If we can come up with a good way of generating the reference keys, we can still change the current format.

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?

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.

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. 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). All lower case. This is very informative and easy for all users. It also means the key is valid for both HTML and XML uses (e.g., as a name or id). 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. Alan Isaac

2009/1/12 Alan G Isaac <aisaac@american.edu>:

...

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.

On 1/12/2009 2:35 AM Stéfan van der Walt apparently wrote:

We automatically renumber the citations to take care of this.

But this just creates a different inconsistency: different numbers refer to the same article, and additionally that article citation might be formatted in so many different ways that it is difficult to determine that it is in fact the same article. There really is no substitute for using real cite keys and a central database of citations. Alan Isaac

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.)

On 1/13/2009 1:55 PM Tim Michelsen apparently wrote:

Please have a look at: http://bitbucket.org/birkenfeld/sphinx/issue/63/make-sphinx-read-bibtex-file...

And the example Sphinx project at: #3 - http://bitbucket.org/birkenfeld/sphinx/issue/63/make-sphinx-read-bibtex-file...

I would appreciate very much to receive any feedback on my approach.

If I understand, you are using bib4txt.py to do this? Then I can offer to help if you run into problems. Note that bib4txt can do citation reference substitution. I cannot tell if you are doing that separately. You did not say specifically what the docstring problem is, but the obvious difficulty is the following: in a document a reference points to a citation *in that document*, while in a docstring it is not clear whether you want that. (I.e., should the citation text be in the docstring or in a file of citations from all the docstrings?) Alan Isaac

If I understand, you are using bib4txt.py to do this? Yes, I use bib4txt.py. The extension just runs bib4txt.py over all documents to extract the citations. Then it creates the reference file. The bibtex file is also converted to ReSt using your tools.

Then I can offer to help if you run into problems. The problem above is where you or Georg Brandl or anyone familiar with

Note that bib4txt can do citation reference substitution. I cannot tell if you are doing that separately. No, I am not doing this. I create my reference keys in JabRef. The program is cross platform has an automatic bibtex key generator which works according to your defined

But since the bibstuff needs the citation reference to be in a sting object, I cannot process the docstrings in order to create the literature file with only the referenced citations. I therefore just include all references as a workaround. the way Sphinx processes the docstrings works. pattern. => This is just the answer to your question on reference formatting. The scipy/numpy community just needs to agree on a common reference pattern. Say: author_year or authoretal_shorttitle_year and jabref or any other program can take care of the rest.

You did not say specifically what the docstring problem is, but the obvious difficulty is the following: in a document a reference points to a citation *in that document*, while in a docstring it is not clear whether you want that. (I.e., should the citation text be in the docstring or in a file of citations from all the docstrings?) Please take a look at the zip file from the bugreport at bitbucket. I am keen to see what you think. You have more X-perience and may suggest some improvements. It comes with a todo / readme.

... nice to see, that my efforts are of use for you. Kind regards, Timmie

Hi Tim 2009/1/22 Tim Michelsen <timmichelsen@gmx-topmail.de>:

did you already come to a conclusion regarding this cite topic?

Did you try to run the bibtext extension for Sphinx?

I haven't tried it. One difficulty is that each docstring needs to be self-contained, i.e., it must include its own references. If you want to maintain a central reference list, this list must either be generated from the docstrings or, alternatively, the docstrings must be built from the list. I don't think the latter is an option really (since it would require massive merges whenever a reference is updated). What it then comes down to, is that there is work to be done in the documentation editor before we modify the standard. Unfortunately, I am flat broke when it comes to free time, but hopefully some other people have more time to invest in the issue. Regards, Stéfan