From d43ee8b8b429b77e0539bc72ce9ec2e4e0c772df Mon Sep 17 00:00:00 2001
From: Arnaud Gallou <67476099+arnaudgallou@users.noreply.github.com>
Date: Mon, 29 Jul 2024 11:58:20 +0200
Subject: [PATCH] Tweak documentation (#5)

---
 R/pkrt-list.R    |  8 ++++----
 R/pkrt.R         |  4 +++-
 README.Rmd       |  7 +++++--
 README.md        | 10 +++++++---
 man/pkrt.Rd      |  4 +++-
 man/pkrt_list.Rd |  8 ++++----
 6 files changed, 26 insertions(+), 15 deletions(-)

diff --git a/R/pkrt-list.R b/R/pkrt-list.R
index 38e4cfc..60e21e6 100644
--- a/R/pkrt-list.R
+++ b/R/pkrt-list.R
@@ -5,11 +5,11 @@
 #'   automatically references the cited packages in the first (by default)
 #'   `.bib` file specified in the YAML header if no references of the packages
 #'   already exist.
-#' @param ... Character vectors, separated by a comma, of packages to cite.
+#' @param ... Character vectors, separated by commas, of packages to cite.
 #' @details
-#' This function automatically discards duplicate and base packages. I recommend
-#' using `pkrt_list()` in combination with `renv::dependencies()` to cite all
-#' the packages used in a project.
+#' This function automatically discards duplicate and base packages. You can use
+#' `pkrt_list()` in combination with `renv::dependencies()` to cite all the
+#' packages used in a project or directory.
 #' @return A list of package citations.
 #' @examples
 #' # Create a list of citations
diff --git a/R/pkrt.R b/R/pkrt.R
index 8417d4d..9846695 100644
--- a/R/pkrt.R
+++ b/R/pkrt.R
@@ -4,10 +4,12 @@
 #'   in which case `pkrt()` automatically references the cited package in the
 #'   first (by default) `.bib` file specified in the YAML header if no
 #'   references of the package already exist.
-#' @param x A string of the package to cite. Use `pkrt("R")` to cite R.
+#' @param x A string of the package to cite.
 #' @returns A character string.
 #' @examples
 #' pkrt("pakret")
+#'
+#' pkrt("R")
 #' @export
 pkrt <- function(x) {
   check_character(x)
diff --git a/README.Rmd b/README.Rmd
index 0e107af..01331c1 100644
--- a/README.Rmd
+++ b/README.Rmd
@@ -33,7 +33,7 @@ make_template <- function(lines, to_render = TRUE) {
 
 ## Overview
 
-pakret is a minimalist R package citation tool to reference and cite R packages and objects on the fly in R Markdown and Quarto.
+pakret is a minimalist R package citation tool to reference and cite R and R packages on the fly in R Markdown and Quarto.
 
 ## Installation
 
@@ -46,7 +46,7 @@ pak::pak("arnaudgallou/pakret")
 
 ## Usage
 
-Simply use `pkrt()` whenever you want to cite an R package or object in your document:
+Simply use `pkrt()` whenever you want to cite R or an R package in your document:
 
 ````{r, include = FALSE}
 template <- pakret:::dedent('
@@ -147,3 +147,6 @@ make_template(template) |>
   pakret:::read_local_file() |>
   cat()
 ```
+
+By default, pakret writes new references into the first `.bib` file specified in the bibliography list.
+You can change which `.bib` file to save references to using `pkrt_set()`.
diff --git a/README.md b/README.md
index 251ee89..132cb93 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](h
 ## Overview
 
 pakret is a minimalist R package citation tool to reference and cite R
-packages and objects on the fly in R Markdown and Quarto.
+and R packages on the fly in R Markdown and Quarto.
 
 ## Installation
 
@@ -26,8 +26,8 @@ pak::pak("arnaudgallou/pakret")
 
 ## Usage
 
-Simply use `pkrt()` whenever you want to cite an R package or object in
-your document:
+Simply use `pkrt()` whenever you want to cite R or an R package in your
+document:
 
     ---
     bibliography: references.bib
@@ -110,3 +110,7 @@ Here’s the result:
     Alea Jacta Est*.
 
     Itisalapsus, Julius. 2024. *Bar: Tempus Edax Rerum*.
+
+By default, pakret writes new references into the first `.bib` file
+specified in the bibliography list. You can change which `.bib` file to
+save references to using `pkrt_set()`.
diff --git a/man/pkrt.Rd b/man/pkrt.Rd
index 06e3bb1..7a148b0 100644
--- a/man/pkrt.Rd
+++ b/man/pkrt.Rd
@@ -7,7 +7,7 @@
 pkrt(x)
 }
 \arguments{
-\item{x}{A string of the package to cite. Use \code{pkrt("R")} to cite R.}
+\item{x}{A string of the package to cite.}
 }
 \value{
 A character string.
@@ -21,4 +21,6 @@ references of the package already exist.
 }
 \examples{
 pkrt("pakret")
+
+pkrt("R")
 }
diff --git a/man/pkrt_list.Rd b/man/pkrt_list.Rd
index eda6304..6976c8f 100644
--- a/man/pkrt_list.Rd
+++ b/man/pkrt_list.Rd
@@ -7,7 +7,7 @@
 pkrt_list(...)
 }
 \arguments{
-\item{...}{Character vectors, separated by a comma, of packages to cite.}
+\item{...}{Character vectors, separated by commas, of packages to cite.}
 }
 \value{
 A list of package citations.
@@ -21,9 +21,9 @@ automatically references the cited packages in the first (by default)
 already exist.
 }
 \details{
-This function automatically discards duplicate and base packages. I recommend
-using \code{pkrt_list()} in combination with \code{renv::dependencies()} to cite all
-the packages used in a project.
+This function automatically discards duplicate and base packages. You can use
+\code{pkrt_list()} in combination with \code{renv::dependencies()} to cite all the
+packages used in a project or directory.
 }
 \examples{
 # Create a list of citations