use_citation()

[jennybc]

No description provided.

[jennybc]

I opened this when I thought I needed to create a CITATION file, but then I found a way to add specific metadata to standard places and make peace with the auto-produced citation.

So I'm not sure if this is worth doing? But here was the motivation for the record:

Could it somehow be easier to exert some control over what citation() shows w/o taking full control? Right now the choice feels quite stark.

[jsta]

I could see a use_citation() function that creates a file matching the output of knitr::write_bib() which I find to be nicer than the default citation().

[hadley]

@jennybc what in particular do you want to control?

[jennybc]

I wanted to exert some control, like displaying DOI, without have to specify the fields where automatic value is fine (name, title, package version, year, etc.).

During the course of development, I swear the URLs were showing up as a note in the citation entry. The current README is evidence of this:

citation("gapminder")
#> 
#> To cite package 'gapminder' in publications use:
#> 
#>   Jennifer Bryan (NA). gapminder: Data from Gapminder.
#>   https://github.com/jennybc/gapminder,
#>   http://www.gapminder.org/data/,
#>   https://doi.org/10.5281/zenodo.594018.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Manual{,
#>     title = {gapminder: Data from Gapminder},
#>     author = {Jennifer Bryan},
#>     note = {https://github.com/jennybc/gapminder,
#> http://www.gapminder.org/data/,
#> https://doi.org/10.5281/zenodo.594018},
#>   }

But I just-reinstalled gapminder from CRAN and I see that the URLs and the DOI are, in fact, now showing up 😖 so I have not succeeded.

citation("gapminder")
#> 
#> To cite package 'gapminder' in publications use:
#> 
#>   Jennifer Bryan (2017). gapminder: Data from Gapminder. R package
#>   version 0.3.0. https://CRAN.R-project.org/package=gapminder
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Manual{,
#>     title = {gapminder: Data from Gapminder},
#>     author = {Jennifer Bryan},
#>     year = {2017},
#>     note = {R package version 0.3.0},
#>     url = {https://CRAN.R-project.org/package=gapminder},
#>   }

[hadley]

Citations that I've created:

• https://github.com/tidyverse/ggplot2/blob/master/inst/CITATION
• https://github.com/hadley/plyr/blob/master/inst/CITATION
• https://github.com/tidyverse/lubridate/blob/master/inst/CITATION
• https://github.com/r-lib/testthat/blob/master/inst/CITATION
• https://github.com/hadley/reshape/blob/master/inst/CITATION

All citations on CRAN: https://github.com/search?q=org%3Acran+CITATION+in%3Apath&type=Code

gapminder currently doesn't have a citation file (and I don't think it's needed unless you have a paper to cite)

I'd suggest a basic template like:

citHeader("To cite {{Package}} in publications use:")

citEntry(
  entry    = "Article",
  title    = ,
  author   = ,
  journal  = ,
  year     = ,
  volume   = ,
  number   = ,
  pages    = ,
  url      = ,
  textVersion = paste(
    
  )
)

[jennybc]

gapminder currently doesn't have a citation file (and I don't think it's needed unless you have a paper to cite)

#' Use this if you want to encourage users of your package to cite an
#' article or book.

FWIW my interest in this was a user request for making it easy to cite the package itself:

jennybc/gapminder#19

I don't think this is only about books or articles, but also about citing software and, e.g., recording which version was used.

[hadley]

Hmmm, in that case then I think the problem is outside of the scope of usethis

[jooyoungseo]

use_citation() does not work right now since "CITATION" template has not yet been provided.
Could you please add the template?

usethis::use_template("CITATION")
#> Error: Could not find template 'CITATION'in package 'usethis'.

^{Created on 2018-12-04 by the reprex package (v0.2.1.9000)}

Session info

devtools::session_info()
#> - Session info ----------------------------------------------------------
#>  setting  value                       
#>  version  R version 3.5.1 (2018-07-02)
#>  os       Windows 10 x64              
#>  system   x86_64, mingw32             
#>  ui       RTerm                       
#>  language (EN)                        
#>  collate  English_United States.1252  
#>  ctype    English_United States.1252  
#>  tz       America/New_York            
#>  date     2018-12-04                  
#> 
#> - Packages --------------------------------------------------------------
#>  package     * version    date       lib
#>  assertthat    0.2.0      2017-04-11 [1]
#>  backports     1.1.2      2017-12-13 [1]
#>  base64enc     0.1-3      2015-07-28 [1]
#>  callr         3.0.0      2018-08-24 [1]
#>  cli           1.0.1      2018-09-25 [1]
#>  crayon        1.3.4      2017-09-16 [1]
#>  desc          1.2.0      2018-05-01 [1]
#>  devtools      2.0.1.9000 2018-12-02 [1]
#>  digest        0.6.18     2018-10-10 [1]
#>  evaluate      0.12       2018-10-09 [1]
#>  fs            1.2.6      2018-08-23 [1]
#>  glue          1.3.0      2018-10-31 [1]
#>  highr         0.7        2018-06-09 [1]
#>  htmltools     0.3.6      2017-04-28 [1]
#>  knitr         1.20.22    2018-11-13 [1]
#>  magrittr      1.5        2014-11-22 [1]
#>  memoise       1.1.0      2017-04-21 [1]
#>  pkgbuild      1.0.2      2018-10-16 [1]
#>  pkgload       1.0.2      2018-10-29 [1]
#>  prettyunits   1.0.2      2015-07-13 [1]
#>  processx      3.2.0      2018-08-16 [1]
#>  ps            1.2.1      2018-11-06 [1]
#>  R6            2.3.0      2018-10-04 [1]
#>  Rcpp          1.0.0.1    2018-12-03 [1]
#>  remotes       2.0.2      2018-10-30 [1]
#>  rlang         0.3.0.9000 2018-12-02 [1]
#>  rmarkdown     1.10.16    2018-11-19 [1]
#>  rprojroot     1.3-2      2018-01-03 [1]
#>  sessioninfo   1.1.1      2018-11-05 [1]
#>  stringi       1.2.4      2018-07-20 [1]
#>  stringr       1.3.1.9000 2018-09-19 [1]
#>  testthat      2.0.1      2018-10-13 [1]
#>  usethis       1.4.0.9000 2018-12-04 [1]
#>  withr         2.1.2      2018-03-15 [1]
#>  xfun          0.4        2018-10-23 [1]
#>  yaml          2.2.0      2018-07-25 [1]
#>  source                            
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.0)                    
#>  CRAN (R 3.5.0)                    
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.1)                    
#>  Github (r-lib/devtools@a6bbe87)   
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.1)                    
#>  Github (tidyverse/glue@35c61e9)   
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.1)                    
#>  Github (yihui/knitr@dc5ead7)      
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.1)                    
#>  Github (RcppCore/Rcpp@0664c1a)    
#>  CRAN (R 3.5.1)                    
#>  Github (hadley/rlang@035d279)     
#>  Github (rstudio/rmarkdown@34d2fd0)
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.1)                    
#>  Github (hadley/stringr@0b5a4c4)   
#>  CRAN (R 3.5.1)                    
#>  Github (r-lib/usethis@c00a678)    
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.1)                    
#>  CRAN (R 3.5.1)                    
#> 
#> [1] C:/Program Files/R/R-3.5.1/library

[hadley]

Shoot, I somehow managed to not check that file in. I'll fix momentarily.