citEntry                package:utils                R Documentation

Writing Package CITATION Files

Description:

     The 'CITATION' file of R packages contains an annotated list of
     references that should be used for citing the packages.

Usage:

     citEntry(entry, textVersion, header = NULL, footer = NULL, ...)
     citHeader(...)
     citFooter(...)
     readCitationFile(file, meta = NULL)

Arguments:

   entry: a character string with a BibTeX entry type

textVersion: a character string with a text representation of the
          reference

  header: a character string with optional header text

  footer: a character string with optional footer text

    file: a file name

     ...: see details below

    meta: a list of package metadata as obtained by
          'packageDescription', or 'NULL' (default).

Details:

     The 'CITATION' file of an R package should be placed in the 'inst'
     subdirectory of the package source. The file is an R source file
     and may contain arbitrary R commands including conditionals and
     computations. The file is 'source()'ed by the R parser in a
     temporary environment and all resulting objects of class
     '"citation"' (the return value of 'citEntry') are collected.

     Typically the file will contain zero or more calls to 'citHeader',
     then one or more calls to 'citEntry', and  finally zero or more
     calls to  'citFooter'. 'citHeader' and 'citFooter' are simply
     wrappers to 'paste', and their '...' argument is passed on to
     'paste' as is.

Value:

     'citEntry' returns an object of class '"citation"',
     'readCitationFile' returns an object of class '"citationList"'.

Entry Types:

     'citEntry' creates '"citation"' objects, which are modeled after
     BibTeX entries. The entry should be a valid BibTeX entry type,
     e.g.,

     article: An article from a journal or magazine.

     book: A book with an explicit publisher.

     inbook: A part of a book, which may be a chapter (or section or
          whatever) and/or a range of pages.  

     incollection: A part of a book having its own title.

     inproceedings: An article in a conference proceedings.

     manual: Technical documentation like a software manual.

     mastersthesis: A Master's thesis.

     misc: Use this type when nothing else fits.

     phdthesis: A PhD thesis.

     proceedings: The proceedings of a conference.

     techreport: A report published by a school or other institution,
          usually numbered within a series.

     unpublished: A document having an author and title, but not
          formally published.

Entry Fields:

     The '...' argument of 'citEntry' can be any number of BibTeX
     fields, including

     address: The address of the publisher or other type of
          institution.

     author: The name(s) of the author(s), either  as a character
          string in the format described in the LaTeX book, or a
          'personList' object.

     booktitle: Title of a book, part of which is being cited.

     chapter: A chapter (or section or whatever) number.

     editor: Name(s) of editor(s), same format as 'author'.

     institution: The publishing institution of a technical report.

     journal: A journal name.

     note: Any additional information that can help the reader. The
          first word should be capitalized.

     number: The number of a journal, magazine, technical report, or of
          a work in a series.

     pages: One or more page numbers or range of numbers.

     publisher: The publisher's name.

     school: The name of the school where a thesis was written.

     series: The name of a series or set of books.

     title: The work's title.

     volume: The volume of a journal or multi-volume book.

     year: The year of publication.

Examples:

     basecit <- system.file("CITATION", package="base")
     source(basecit, echo=TRUE)
     readCitationFile(basecit)

