[Rd] R package BibTex entries: looking for a more general solution

[Michael Friendly]

== Summary ==
* Problem: BibTeX entries extracted from R packages via citation() 
require too much manual editing to be
of general use.
* Proposal: Date: fields should be made mandatory in package DESCRIPTION 
files, perhaps
beginning with warnings from R CMD check
* Proposal: Package authors should be encouraged to use a (new) 
Contributors: field in the DESCRIPTION file
rather than packing all information into the Author: field, which at 
present cannot often be parsed by BibTeX.
* Files: All test files referred to here can be found at

http://euclid.psych.yorku.ca/SCS/Private/Rbibs/

== Details ==
Around 16 Dec. 2009, I queried R-help about automating the extraction of 
citation()s from R packages. The stimulus
was that some journals, notably JSS, now require a reference and 
citation of every R package mentioned,
and it is a pain to create these manually, no less maintain them for 
current versions.

The result of that query was a function, Rpackage.bibs() by Achim 
Zeileis that I have been using ever since.
Code in: http://euclid.psych.yorku.ca/SCS/Private/Rbibs/Rpackages.bib.R
On one current system I get the following:

 > Rpackage.bibs(file="Rpackages-R.2.11.1.bib")
Converted 230 of 230 package citations to BibTex
Results written to file Rpackages-R.2.11.1.bib
Warning messages:
1: In citation(x) :
no date field in DESCRIPTION file of package 'codetools'
2: In citation(x) :
no date field in DESCRIPTION file of package 'gridBase'
3: In citation(x) : no date field in DESCRIPTION file of package 'iplots'
 >
See:
http://euclid.psych.yorku.ca/SCS/Private/Rbibs/Rpkg-test.pdf
for the result of processing this .bib file with latex/bibtex using the 
jss.bst bibliography style

I'm writing to R-Devel because the DESCRIPTION and inst/CITATION files 
in R packages provide the
basic data used in citation() and any methods based on this, and yet the 
information in these files is
often insufficient to generate well-formed BibTeX entries for use in 
vignettes and publications.

One easy case is illustrated above, where 3 packages have no Date: field 
so the BibTeX gets no
year = {},
and references get printed as Murrell, P (????) for gridBase. (In my 
original test under R 2.9.1, there where
~ 20 such warnings.) Thus, I propose that Date: be a required field in 
DESCRIPTION files, and
R CMD check complain if this is not found.

The more difficult case has to do with the Author: field in the 
DESCRIPTION file (when no CITATION file is present)
People can write whatever they want here, and the result looks sort of 
OK when printed by citation(), but confuses
BibTeX mightly. One example:

 > citation("akima")
To cite package ‘akima’ in publications use:

Fortran code by H. Akima R port by Albrecht Gebhardt aspline function
by Thomas Petzoldt <petzoldt at rcs.urz.tu-dresden.de> enhancements and
corrections by Martin Maechler (2009). akima: Interpolation of
irregularly spaced data. R package version 0.5-4.
http://CRAN.R-project.org/package=akima

A BibTeX entry for LaTeX users is

@Manual{,
title = {akima: Interpolation of irregularly spaced data},
author = {Fortran code by H. Akima R port by Albrecht Gebhardt aspline 
function by Thomas Petzoldt <petzoldt at rcs.urz.tu-dresden.de> 
enhancements and corrections by Martin Maechler},
year = {2009},
note = {R package version 0.5-4},
url = {http://CRAN.R-project.org/package=akima},
}

ATTENTION: This citation information has been auto-generated from the
package DESCRIPTION file and may need manual editing, see
‘help("citation")’ .
 >

Yes, the ATTENTION note does say that manual editing may be necessary, 
but I think a worthy goal would be
to try to reduce the need for this.

One simple way to do that would be to support an extra Contributions: 
field in the DESCRIPTION file,
so that Authors: can be more cleanly separated for the purpose of 
creating well-structured BibTeX.
Perhaps others have better ideas.

-Michael

-- 
Michael Friendly     Email: friendly AT yorku DOT ca
Professor, Psychology Dept.
York University      Voice: 416 736-5115 x66249 Fax: 416 736-5814
4700 Keele Street    Web:http://www.datavis.ca
Toronto, ONT  M3J 1P3 CANADA