Re: [Numpy-discussion] coding style: citations
... citations ... BibTeX
Please ensure that, whatever you come up with, it is *very intuitive* for the writer to enter the citation data, or we will quickly lose citations, and possibly writers. For example, I would not have them type in BibTeX entries, but rather provide boxes where they can enter the title, author, etc. and have the system generate the BibTeX. Not everyone uses BibTeX, and the rules about braces, what fields are required, etc., are not totally trivial. Perhaps there's a web site out there that does this already, if BibTex is to be our internal format (which I'm not at all opposed to; I use it myself). If a large majority of our current writers thinks BibTeX is ok, then I'll change my mind. We should poll them on the acceptability of any proposed system before implementing it. For citation keys, what's wrong with good old author-year format? Most scientific journals use it (Abt 1985). --jh-- Abt, H. 1985. Harold Abt used to publish surveys of things like citations when he was ApJ editor in the 1980s but I'm making this one up just to demonstrate the format except he'd never allow an article title in a citation because he wanted to save ink which everyone hated so other journals keep the titles and we should too. ApJ 123:1-23.
On 1/12/2009 9:08 AM jh@physics.ucf.edu apparently wrote:
For citation keys, what's wrong with good old author-year format? Most scientific journals use it (Abt 1985). Abt, H. 1985. Harold Abt used to publish surveys of things like citations when he was ApJ editor in the 1980s but I'm making this one up just to demonstrate the format except he'd never allow an article title in a citation because he wanted to save ink which everyone hated so other journals keep the titles and we should too. ApJ 123:1-23.
There are two problems. 1. The only real problem is that it is not a reST citation, so links to the citation will not be generated, and you cannot control the citation formatting separately. You can still of course use normal internal targets: See `(Abt 1985)`_. Some more text, and later ... .. _(Abt 1985): Abt, H. 1985. Harold Abt used to publish surveys of things like citations when he was ApJ editor in the 1980s but I'm making this one up just to demonstrate the format except he'd never allow an article title in a citation because he wanted to save ink which everyone hated so other journals keep the titles and we should too. ApJ 123:1-23. 2. The failure to use citation keys implies that there will be neither a citation database nor consistent formatting. (Say, if the docs become a book.) I do not suppose this is *currently* a real problem. Cheers, Alan Isaac
participants (2)
-
Alan G Isaac
-
jh@physics.ucf.edu