Package knitcitations

Transcription

1 Package knitcitations March 18, 2013 Type Package Title Citations for knitr markdown files Version knitcitations provides the ability to create dynamic citations in which the bibliographic information is pulled from the web rather than having to be entered into a local database such as bibtex ahead of time. Knitcitations is primarily aimed at authoring in the R markdown format, and can provide outputs for web-based authoring such as linked text and tooltips over inline citations. Cite using a DOI, URL, or bibtex file key. See the package URL for details. URL Depends R (>= ), knitr, bibtex Imports xtable, RCurl, XML, httr Suggests testthat License CC0 Collate functiontable.r bibliography.r formatref.r ref.r cite.r create_bibkey.r citep.r citet.r read.bibtex.r write.b Author Carl Boettiger [aut, cre] Maintainer Carl Boettiger <cboettig@gmail.com> NeedsCompilation no Repository CRAN Date/Publication :26:33 1

2 2 authoryear_p R topics documented: authoryear_p authoryear_t bibliography cite citep citet cite_options cleanbib format_authoryear_p format_authoryear_t functiontable greycite newbib numeral read.bibtex ref write.bibtex write_cache Index 14 authoryear_p format the author and year This is just a utility function that calls format_authoryear_p, which does the actual formating at the time the citation is added to the data. This provides a separate API for the function that simply returns the formatted text, from the function that does the formatting (which may change, or may have more flavors, etc). authoryear_p(entry, format_inline_fn = format_authoryear_p) entry a bibentry format_inline_fn the function that actually creates the inline format for a single entry the author-year citation

3 authoryear_t 3 authoryear_t format the author and year format the author and year authoryear_t(entry, format_inline_fn = format_authoryear_t) entry a bibentry format_inline_fn the function that actually creates the inline format for a single entry the author-year citation bibliography Generate the bibliography Generate the bibliography bibliography(style = "markdown",.bibstyle = "JSS", ordering = c("authors", "year", "title", "journal", "volume", "number", "pages", "doi", "url"), sort = FALSE, bibtex = get("bibtex_data", envir = knitcitations_options),...) style ordering formatting style to print bibliography (default is plain text). Can be text, bibtex, html, textversion, R, citation, or other formats defined forthe print bibentry class, see?print.bibentry for details. a character list of the order in which information should be printed (e.g. c("author", "year", "title", "journal", "volume", "number", "pages", "doi", "uri")) see details. Works only for rdfa and markdown formats at the moment. Other styles are formatted according to the bibstyle method, see for more information.

4 4 cite sort bibtex.bibstyle logical indicating if bibliography should be sorted alphabetically, defaults to FALSE logical, use bibtex data structure internally? (internal option only) the bibstyle function call or string. Defaults to journal of statistical software (JSS). See bibstyle.... additional arguments passed to print.bibentry, see bibentry The markdown and rdfa print formats can take the argument ordering. A character string provides the order in which elements should be returned. Elements not specified are omitted from the return entirely. Even if both DOI or URI (usually the URL) are given, method will return the URL only if the DOI is absent/unavailable. a list of bibentries, providing a bibliography of what s been cited Examples citet(citation("knitr")) bibliography() ## use markdown formatting, show only author, year, and url bibliography("markdown", ordering = c("authors", "year", "url")) ## Repeat citations do not create duplicates: bib <- c(citation("knitr"), citation("knitr"), citation("bibtex"), citation("bibtex"), citation("knitr"), citat citep(bib) bibliography() cite Add a citation (internal for citet and citep) Add a citation (internal for citet and citep) cite(x, bibtex = get("bibtex_data", envir = knitcitations_options), format_inline_fn = format_authoryear_p)

5 citep 5 x a doi or list of dois, or a bibentry (or list of bibentries) bibtex internal logical indicating if we use a cache or external bibtex file format_inline_fn a function which will create the inline citation format (stored with the entry to avoid non-unique citation styles, e.g. Boettiger 2012a, Boettiger 2012b.) Stores the full citation in a "works_cited" list, which can be printed with bibliography a parenthetical inline citation Examples citep(" / ") citep Add a paranthetical citation Add a paranthetical citation x citep(x,..., format_inline_fn = format_authoryear_p, inline_format = authoryear_p) a doi or list of dois, or a bibentry (or list of bibentries) inline_format a function for formating the inline citation, defaults to authoryear_t format_inline_fn function to format a single inline citation... additional arguments passed to citet, see citet for details Stores the full citation in a "works_cited" list, which can be printed with bibliography A variety of reasons for the citation can be provided following the CiTO ontology: c("cites","citesasauthority", "citesasmetadatadocument", "citesassourcedocument","citesforinformation", "iscitedby","obtainsbackgroundfrom", "sharesauthorswith", "usesdatafrom", "usesmethodin", "confirms", "credits", "extends", "obtainssupportfrom", "supports", "updates", "corrects", "critiques", "disagreeswith", "qualifies", "refutes", "discusses", "reviews")

6 6 citet a parenthetical inline citation Examples library(knitcitations) citep(" / ") ## Read in the bibtex information for some packages: knitr <- citation("knitr") knitcitations <- citation("knitcitations") # generate the parentetical citation for these: citep(list(knitr,knitcitations)) # generate the full bibliography: bibliography() ## Assign a citation key to a doi and then use it later: citep(c(halpern2006=" /j x")) citep("halpern2006") citet Add a textual citation Parameters listed here are the same for parenthetical citation, citep. x cito citet(x, cito = NULL, tooltip = get("tooltip", envir = knitcitations_options), linked = get("linked", envir = knitcitations_options), numerical = get("numerical", envir = knitcitations_options), format_inline_fn = format_authoryear_t, inline_format = authoryear_t) tooltip linked a doi or list of dois, or a bibentry (or list of bibentries) Semantic reason for the citation. Only active if linked=true Show a citation information on mouseover. Requires the tooltip javascript from Pass logical TRUE/FALSE or set default behavior with cite_options link the inline citation text to the resource by doi (if available) or url? Pass logical TRUE/FALSE or set default behavior with cite_options numerical use citation instead of author-year format? (Not functional yet!) Pass logical TRUE/FALSE or set default behavior with cite_options format_inline_fn function to format a single inline citation

7 cite_options 7 inline_format a function for formating the inline citation, defaults to authoryear_t (designed for internal use only) Stores the full citation in a "works_cited" list, which can be printed with bibliography. A variety of reasons for the citation can be provided following the CiTO ontology: c("cites","citesasauthority", "citesasmetadatadocument", "citesassourcedocument","citesforinformation", "iscitedby","obtainsbackgroundfrom", "sharesauthorswith", "usesdatafrom", "usesmethodin", "confirms", "credits", "extends", "obtainssupportfrom", "supports", "updates", "corrects", "critiques", "disagreeswith", "qualifies", "refutes", "discusses", "reviews") a text inline citation Examples library(knitcitations) citet(" / ") ## Read in the bibtex information for some packages: knitr <- citation("knitr") citet(knitr) # generate the full bibliography: bibliography() ## Assign a citation key to a doi and then use it later: citet(c(halpern2006=" /j x")) citet("halpern2006") cite_options Toggles for various citation options Toggles for various citation options cite_options(tooltip = FALSE, linked = TRUE, numerical = FALSE, bibtex_data = FALSE) tooltip linked numerical bibtex_data Provide a javascript tooltip over the in-line citation? (requires twitter-bootstrap tooltip JS, see details). Add an HTML link around the in-line citation? Use numerical instead of author-year format citations? whether we should write to a bibtex file instead of the knitcitationscache environment for tracking bibliographic information of what we have already cited.

8 8 format_authoryear_p updates the option specified for the duration of the session. cleanbib Erase existing list of works cited Erase existing list of works cited cleanbib(bibtex = get("bibtex_data", envir = knitcitations_options)) bibtex logical, internal use parameter only. simply overwrites knitcitations.bib in bibtex data logging mode. (which means bibtex is used for internal data; not that the input data comes from bibtex. Input data can come from any source, bibtex or DOI, as shown in the documentation). format_authoryear_p format the author and year parenthetically This formats a single entry, though adjusted by author. This function is passed down to cite by citep, wher it creates the actuall formatting on the first use. format_authoryear_p(entry, char = "") entry char a bibentry a character to append to the citation (to disambiguate). This is handled automatically by the cite function. the author-year citation

9 format_authoryear_t 9 format_authoryear_t format the author and year This formats a single entry, though adjusted by author. This function is passed down to cite by citet, wher it creates the actuall formatting on the first use. format_authoryear_t(entry, char = "") entry char a bibentry a character to append to the citation (to disambiguate). This is handled automatically by the cite function. the author-year citation functiontable a table of functions in a package This function takes a package name an generates a two-column table with the names of each function in the package and the short description from the help documentation. pkg functiontable(pkg,...) a string specifying the name of a package,... additional arguments to xtable useful for Sweave/knit manuals specifying a table of functions Note that xtable format can also be set with options(xtable.type="latex") or options(xtable.type="html"). This function modified from DWin s solution on StackOverflow.com,

10 10 newbib the output of xtable (as html, or specify type="latex") Examples functiontable("xtable") greycite greycite citation method Grab citation data using the greycite API greycite(url, format = c("bib", "json")) url format the website URL have greycite return data in bib (bibtex) or json format? a bibentry class object newbib Erase existing list of works cited Erase existing list of works cited newbib(bibtex = get("bibtex_data", envir = knitcitations_options)) bibtex logical, internal use parameter only. simply overwrites knitcitations.bib in bibtex data logging mode. (which means bibtex is used for internal data; not that the input data comes from bibtex. Input data can come from any source, bibtex or DOI, as shown in the documentation).

11 numeral 11 numeral Formatting for numeric inline citations. Needs testing. Formatting for numeric inline citations. Needs testing. numeral(entry) entry a bibentry object, e.g. from cite read.bibtex read in bibtex and use key as list names read in bibtex and use key as list names read.bibtex(bibfile) bibfile a bibtex.bib file this differs from read.bib in that the list is named. this allows one to use citep(bib[c("key1", "key2")] a list of citation information See Also read.bib citep citet

12 12 write.bibtex ref Lookup article info via CrossRef with DOI. Lookup article info via CrossRef with DOI. doi ref(doi, title = FALSE, url = " key = "cboettig@gmail.com",..., curl = getcurlhandle()) title url key digital object identifier for an article in PLoS Journals return the title of the paper or not (defaults to FALSE) the PLoS API url for the function (should be left to default) your PLoS API key, either enter, or loads from.rprofile... optional additional curl options (debugging tools mostly) curl If using in a loop, call getcurlhandle() first and pass the returned value in here (avoids unnecessary footprint) Metadata from DOI in R s bibentry format. Examples ref(" / ") print(ref(" / "), style="bibtex") print(ref(" / "), style="text") write.bibtex write a bibtex file write a bibtex file write.bibtex(entry, file = "knitcitations.bib", append = FALSE, verbose = TRUE, create_key = TRUE)

13 write_cache 13 entry file append verbose create_key a bibentry object, list of bibentry objects, or a character vector of package names output bibtex file. Will automatically append.bib if not added. if NULL will use stdout. a logical indicating that bibtex entries be added the the file. If FALSE (default), the file is overwritten. a logical to toggle verbosity. If file=null, verbosity is forced off. logical indicating whether function should create a bibtex citation key if the object doesn t have one. a list of citation information, invisibly The knitcitations package automatically extends the use of this function to be able to write bibtex files from a string of DOIs, making it valuable for purposes beyond the citation of packages. See Also read.bib citep citet Examples write.bibtex(c("yihui2013" = citation("knitr"), "Boettiger2013" = citation("knitcitations"), "TempleLang2012"=c bib <- read.bibtex("knitcitations.bib") write_cache write knitcitations data to a cache object instead of a file write knitcitations data to a cache object instead of a file write_cache(a_bibentry, bibtex = get("bibtex_data", envir = knitcitations_options)) a_bibentry bibtex a bibentry object, possibly already named with a key logical, use a bibtex file for the cache of cited works rather than an environment? writes the bibentry to the environment knitcitationscache, created by

14 Index authoryear_p, 2 authoryear_t, 3 bibentry, 4 bibliography, 3, 5, 7 bibstyle, 3, 4 cite, 4 cite_options, 6, 7 citep, 5, 6 citet, 5, 6 cleanbib, 8 format_authoryear_p, 8 format_authoryear_t, 9 functiontable, 9 greycite, 10 newbib, 10 numeral, 11 read.bibtex, 11 ref, 12 write.bibtex, 12 write_cache, 13 14