From Friedrich.Leisch at tuwien.ac.at  Sat Feb  4 16:27:33 2006
From: Friedrich.Leisch at tuwien.ac.at (Friedrich.Leisch@tuwien.ac.at)
Date: Sat, 4 Feb 2006 16:27:33 +0100
Subject: [Rd] Citation of R packages
In-Reply-To: <1578.202.89.153.187.1138576012.squirrel@sqmail.anu.edu.au>
References: <1578.202.89.153.187.1138576012.squirrel@sqmail.anu.edu.au>
Message-ID: <17380.51173.64968.956060@celebrian.ci.tuwien.ac.at>

>>>>> On Mon, 30 Jan 2006 10:06:52 +1100 (EST),
>>>>> John Maindonald (JM) wrote:

  > The bibtex citations provided by citation() do not
  > work all that well in cases where there is no printed
  > document to reference:

That's why there is a warning at the end that they will need manual
editing ... IMHO they at least save you some typing effort in many
cases.

  > (1) A version field is needed, as the note field is
  > required for other purposes, currently trying to
  > sort out nuances that cannot be sorted out in the
  > author list (author, compiler, implementor of R version,
  > contributor, ...) and maybe giving a cross-reference
  > to a book or paper that is somehow relevant.

Why should a reference cross-reference another reference? Could you
give an example?

  > (2) Maybe the author field should be more nuanced, or
  > maybe ...

author fields of bibtex entries have a strict format (names separated
by "and"), what do you mean by "more nuanced"?

  > (3) In compiling a list of packages, name order seems
  > preferable, and one wants the title first (achieved by
  > relocating the format.title field in the manual FUNCTION
  > in the .bst file
  > (4) manual seems not an ideal name for the class, if
  > there is no manual.

A package always has a "reference manual", the concatenated help pages
certainly qualify as such and can be downloaded in PDF format from
CRAN. The ISBN rules even allow to assign an ISBN number to the online
help of a software package which also can serve as the ISBN number of
the *software itself* (which we did for base R).

  > Maybe what is needed is a package or suchlike class,
  > and several alternative .bst files that handle the needed
  > listings.

  > I know at least one other person who is wrestling with
  > this, and others on this list must be wrestling with it.

I am certainly open for discussions and any suggestions for
improvements, but it must be within the standard bibtex entry types,
we cannot write our own entry types and .bst files. Many journals
require the usage of their own (or standard) bibtex styles, and the
entries we produce must work with those. If R creates nonstandard
bibtex entries even more manual work will be necessary in many
cases.

I have no definitive bibtex reference at hand, but the natbib style
files (a very popular collection of bibtex styles, at least I
definitely want to be compatible with those) define

 article
 book
 booklet
 conference  (= alias for inproceedings)
 inbook
 incollection
 inproceedings
 manual
 mastersthesis
 misc
 phdthesis
 proceedings
 techreport
 unpublished

which coincide with the choices the emacs bibtex mode offers. Out of
these only "manual", "misc" and "unpublished" seem appropriate for
packages, and the description suggests to use manual for citing
software manuals, but the definitions of those three are very similar
anyway.

Maybe you could give an example what your candidate for a bibtex entry
for packages should look like?

Best,
Fritz

-- 
-------------------------------------------------------------------
                        Friedrich Leisch 
Institut f?r Statistik                     Tel: (+43 1) 58801 10715
Technische Universit?t Wien                Fax: (+43 1) 58801 10798
Wiedner Hauptstra?e 8-10/1071
A-1040 Wien, Austria             http://www.ci.tuwien.ac.at/~leisch



[Rd] Citation of R packages
Friedrich.Leisch@tuwien.ac.at