Skip to contents

Create a inst/CITATION file

Source: R/write_citation.R
write_citation.Rd

Creates a R CITATION file (inst/CITATION) from the metadata of a CITATION.cff file or cff object.

Usage

write_citation(
  x,
  file = "./inst/CITATION",
  append = FALSE,
  verbose = TRUE,
  ...
)

Arguments

x

It could be

  • A bibentry object created with cff_to_bibtex(), citation() or bibentry()

  • Any of the valid inputs of cff_to_bibtex():

    • A missing value. That would retrieve the DESCRIPTION file on your in-development package.

    • An existing cff object,

    • Path to a CITATION.cff file ("*/CITATION.cff*"),

    • The name of an installed package ("jsonlite"), or

    • Path to a DESCRIPTION file ("*/DESCRIPTION*").

file

Name of the file to write.

append

Whether to append the entries to an existing file or not.

verbose

Display informative messages

...

Arguments passed on to cff_to_bibtex

what

Fields to extract. The value could be:

  • preferred: This would create a single entry with the main citation info of the package.

  • references: Extract all the entries on references.

  • all: A combination of the previous two options. This would extract both the preferred citation info and the references.

Value

Writes an inst/CITATION file and (invisibly) returns the bibentry object that has been written to the file.

Details

For security reasons, if the file already exists the function would create a backup copy on the same directory.

References

R Core Team (2023). "CITATION files." In Writing R Extensions, chapter 1.9, R version 4.3.0 (2023-04-21) edition. https://cran.r-project.org/doc/manuals/R-exts.html#CITATION-files.

See also

bibentry() and style argument.

Other BibTeX helpers: cff_from_bibtex(), cff_to_bibtex(), encoded_utf_to_latex(), write_bib()

Examples

# Use a system file
f <- system.file("examples/preferred-citation-book.cff", package = "cffr")

# Write to tmp dir
out <- file.path(tempdir(), "CITATION")
write_citation(f, file = out)
#> ℹ Writing 1 entry ...
#> ✔ Results written to /tmp/RtmpxOFwT9/CITATION

# Check by reading, use meta object

meta <- packageDescription("cffr")
meta$Encoding <- "UTF-8"

utils::readCitationFile(out, meta)
#> To cite package ‘cffr’ in publications use:
#> 
#>   Bueler E (2021). _PETSc for Partial Differential Equations: Numerical
#>   Solutions in C and Python_. SIAM Press, Philadelphia. ISBN
#>   978111976304, <https://github.com/bueler/p4pdes>.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Book{bueler:2021,
#>     title = {PETSc for Partial Differential Equations: Numerical Solutions in C and Python},
#>     author = {Ed Bueler},
#>     year = {2021},
#>     publisher = {SIAM Press},
#>     address = {Philadelphia},
#>     isbn = {978111976304},
#>     url = {https://github.com/bueler/p4pdes},
#>   }


# Append to the same file
bib2 <- citation()
write_citation(bib2, file = out, append = TRUE)
#> ℹ Creating a backup of /tmp/RtmpxOFwT9/CITATION in /tmp/RtmpxOFwT9/CITATION.bk1
#> ℹ Writing 1 entry ...
#> ✔ Results written to /tmp/RtmpxOFwT9/CITATION

utils::readCitationFile(out, meta)
#> To cite R in publications use:
#> 
#>   Bueler E (2021). _PETSc for Partial Differential Equations: Numerical
#>   Solutions in C and Python_. SIAM Press, Philadelphia. ISBN
#>   978111976304, <https://github.com/bueler/p4pdes>.
#> 
#>   R Core Team (2023). _R: A Language and Environment for Statistical
#>   Computing_. R Foundation for Statistical Computing, Vienna, Austria.
#>   <https://www.R-project.org/>.
#> 
#> We have invested a lot of time and effort in creating R, please cite it
#> when using it for data analysis. See also ‘citation("pkgname")’ for
#> citing R packages.
#> 
#> To see these entries in BibTeX format, use 'print(<citation>,
#> bibtex=TRUE)', 'toBibtex(.)', or set
#> 'options(citation.bibtex.max=999)'.