[Numpy-discussion] coding style: citations

[Stéfan van der Walt]

Hi Alan

2009/1/11 Alan G Isaac <aisaac at american.edu>:
> The docstring standard at
> http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines#docstring-standard
> 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 at scipy.org
> http://projects.scipy.org/mailman/listinfo/numpy-discussion
>