improve text and examples

Author: NewGraphEnvironment

README.Rmd

@@ -19,9 +19,17 @@ knitr::opts_chunk$set(
 ![MaybeNotHelpful](https://img.shields.io/badge/NeverMind-MaybeNotHelpful-green)
 
 This package focuses solely on "extra" functions related to citeing bibliography 
-items such as processing .bib files to get citation keys, processing BiBtex keys to get inline citations, etc.  This work was
-inspired by the need to find a way to process citation keys to inline citation text in DT tables as rendering in rmarkdown does
-not produce the results we desire so we need to do it with manual calls to `pandoc`.
+items such as processing .bib files to get citation keys, processing BiBtex keys to get inline citations, etc.  We
+are calling it "extra" because we rely heavily on [`rbbt`](https://github.com/paleolimbot/rbbt) and standard
+`rmarkdown::render` magic to almost everything we need to do. Some functions for rendering citation keys
+as inline references wrap calls to `pandoc` so that needs to be installed. If you have Rstudion you likely have it already.
+
+This package deals with a few problems as follows:
+
+  - Identify all citation keys in documents and confirm their presence in a specified .bib file.
+  - Highlight citation keys that do not match and suggest the closest matching keys from the .bib file.
+  - Provide workarounds for citation handling in interactive tables [(DT)](https://github.com/rstudio/DT) and other HTML 
+  outputs where standard citation rendering in R Markdown and Quarto may fail.
 
 ## Installation
 
@@ -34,22 +42,39 @@ pak::pkg_install("NewGraphEnvironment/xciter")
 
 ## Example
 
-This is a basic example which shows you how to solve a common problem:
+This is a basic example of subbing citation keys for inline references within a table so that it can
+be rendered as is after the changes are made:
 
 ```{r example}
 library(xciter)
 ## basic example code
 
-path_bib <- system.file("extdata", "references.bib", package = "xciter")
+path_bib <- system.file("extdata", "NewGraphEnvironment.bib", package = "xciter")
 dat <- data.frame(
   id = 1:3,
   bib_keys = c(
     "Outside block quotes @busch_etal2011LandscapeLevelModela and in [@woll_etal2017SalmonEcological]",
-    "This is many [@busch_etal2011LandscapeLevelModela; @woll_etal2017SalmonEcological; @kirsch_etal2014Fishinventory]",
+    "This is many [@busch_etal2011LandscapeLevelModela; @woll_etal2017SalmonEcological; @kirsch_etal2014Fishinventorya]",
     "this is a failed key @key3"
   )
 )
 result <- xct_keys_to_inline_table_col(dat, col_format = "bib_keys", path_bib = path_bib)
 print(result)
 ```
 
+This is a basic example of checking if the citation keys within a bookdown document are found within a specified
+`.bib` file.
+
+```{r}
+key_missing <- xct_bib_keys_missing(path_bib, "kirsch_etal2014Fishinventory")
+```
+
+
+<br>
+
+This is an example of how to search for the closest match for an unmatched key.
+
+```{r}
+xct_keys_guess_match(key_missing, keys_bib = xct_bib_keys_extract(path_bib))
+```
+

README.md

@@ -8,10 +8,23 @@
 
 This package focuses solely on “extra” functions related to citeing
 bibliography items such as processing .bib files to get citation keys,
-processing BiBtex keys to get inline citations, etc. This work was
-inspired by the need to find a way to process citation keys to inline
-citation text in DT tables as rendering in rmarkdown does not produce
-the results we desire so we need to do it with manual calls to `pandoc`.
+processing BiBtex keys to get inline citations, etc. We are calling it
+“extra” because we rely heavily on
+[`rbbt`](https://github.com/paleolimbot/rbbt) and standard
+`rmarkdown::render` magic to almost everything we need to do. Some
+functions for rendering citation keys as inline references wrap calls to
+`pandoc` so that needs to be installed. If you have Rstudion you likely
+have it already.
+
+This package deals with a few problems as follows:
+
+- Identify all citation keys in documents and confirm their presence in
+  a specified .bib file.
+- Highlight citation keys that do not match and suggest the closest
+  matching keys from the .bib file.
+- Provide workarounds for citation handling in interactive tables
+  [(DT)](https://github.com/rstudio/DT) and other HTML outputs where
+  standard citation rendering in R Markdown and Quarto may fail.
 
 ## Installation
 
@@ -25,18 +38,20 @@ pak::pkg_install("NewGraphEnvironment/xciter")
 
 ## Example
 
-This is a basic example which shows you how to solve a common problem:
+This is a basic example of subbing citation keys for inline references
+within a table so that it can be rendered as is after the changes are
+made:
 
 ``` r
 library(xciter)
 ## basic example code
 
-path_bib <- system.file("extdata", "references.bib", package = "xciter")
+path_bib <- system.file("extdata", "NewGraphEnvironment.bib", package = "xciter")
 dat <- data.frame(
   id = 1:3,
   bib_keys = c(
     "Outside block quotes @busch_etal2011LandscapeLevelModela and in [@woll_etal2017SalmonEcological]",
-    "This is many [@busch_etal2011LandscapeLevelModela; @woll_etal2017SalmonEcological; @kirsch_etal2014Fishinventory]",
+    "This is many [@busch_etal2011LandscapeLevelModela; @woll_etal2017SalmonEcological; @kirsch_etal2014Fishinventorya]",
     "this is a failed key @key3"
   )
 )
@@ -51,3 +66,23 @@ print(result)
 #> 2 This is many (Busch et al. 2011; Woll, Albert, and Whited 2017; Kirsch, Buckwalter, and Reed 2014)
 #> 3                                                                       this is a failed key (key3?)
 ```
+
+This is a basic example of checking if the citation keys within a
+bookdown document are found within a specified `.bib` file.
+
+``` r
+key_missing <- xct_bib_keys_missing(path_bib, "kirsch_etal2014Fishinventory")
+#> ! The following citations were not found in the BibTeX file:
+#> [1] "kirsch_etal2014Fishinventory"
+```
+
+<br>
+
+This is an example of how to search for the closest match for an
+unmatched key.
+
+``` r
+xct_keys_guess_match(key_missing, keys_bib = xct_bib_keys_extract(path_bib))
+#>                    key_missing       key_missing_guess_match
+#> 1 kirsch_etal2014Fishinventory kirsch_etal2014Fishinventorya
+```