Convert roxygen to use markdown

Also run usethis::use_tidy_description()

DESCRIPTION

@@ -1,36 +1,49 @@
 Package: xml2
-Version: 1.2.0.9000
 Title: Parse XML
-Description: Work with XML files using a simple, consistent interface. Built on
-    top of the 'libxml2' C library.
-Authors@R: c(
-    person("Hadley", "Wickham", , "hadley@rstudio.com", "aut"),
-    person("Jim", "Hester", , "jim.hester@rstudio.com", c("aut", "cre")),
-    person("Jeroen", "Ooms", role = "aut"),
-    person("RStudio", role = "cph"),
-    person("R Foundation", role = "ctb",
-      comment = "Copy of R-project homepage cached as example")
-    )
+Version: 1.2.0.9000
+Authors@R: 
+    c(person(given = "Hadley",
+             family = "Wickham",
+             role = "aut",
+             email = "hadley@rstudio.com"),
+      person(given = "Jim",
+             family = "Hester",
+             role = c("aut", "cre"),
+             email = "jim.hester@rstudio.com"),
+      person(given = "Jeroen",
+             family = "Ooms",
+             role = "aut"),
+      person(given = "RStudio",
+             role = "cph"),
+      person(given = "R Foundation",
+             role = "ctb",
+             comment = "Copy of R-project homepage cached as example"))
+Description: Work with XML files using a simple, consistent
+    interface. Built on top of the 'libxml2' C library.
+License: GPL (>=2)
 URL: https://xml2.r-lib.org/, https://github.com/r-lib/xml2
 BugReports: https://github.com/r-lib/xml2/issues
 Depends:
     R (>= 3.1.0)
 Imports:
     Rcpp
-LinkingTo: Rcpp (>= 0.12.12)
 Suggests:
-    testthat (>= 2.1.0),
-    curl,
     covr,
+    curl,
+    httr,
     knitr,
-    rmarkdown,
     magrittr,
-    httr,
-    mockery
-SystemRequirements: libxml2: libxml2-dev (deb), libxml2-devel (rpm)
-License: GPL (>=2)
-RoxygenNote: 6.0.1
-VignetteBuilder: knitr
+    mockery,
+    rmarkdown,
+    testthat (>= 2.1.0)
+LinkingTo: 
+    Rcpp (>= 0.12.12)
+VignetteBuilder: 
+    knitr
+Encoding: UTF-8
+RoxygenNote: 6.1.1
+SystemRequirements: libxml2: libxml2-dev (deb), libxml2-devel
+    (rpm)
 Collate: 
     'RcppExports.R'
     'as_list.R'
@@ -55,3 +68,4 @@ Collate:
     'xml_url.R'
     'xml_write.R'
     'zzz.R'
+Roxygen: list(markdown = TRUE)

R/RcppExports.R

@@ -230,7 +230,7 @@ doc_validate <- function(doc, schema) {
 #' @param x A character vector of urls relative to that base
 #' @param base A string giving a base url.
 #' @return A character vector of urls
-#' @seealso \code{\link{xml_url}} to retrieve the URL associated with a document
+#' @seealso [xml_url()] to retrieve the URL associated with a document
 #' @export
 #' @examples
 #' url_absolute(c(".", "..", "/", "/x"), "http://hadley.nz/a/b/c/d")
@@ -252,7 +252,7 @@ url_relative <- function(x, base) {
 #' Parse a url into its component pieces.
 #'
 #' @param x A character vector of urls.
-#' @return A dataframe with one row for each element of \code{x} and
+#' @return A dataframe with one row for each element of `x` and
 #'   columns: scheme, server, port, user, path, query, fragment.
 #' @export
 #' @examples

R/as_list.R

@@ -1,19 +1,19 @@
 #' Coerce xml nodes to a list.
 #'
 #' This turns an XML document (or node or nodeset) into the equivalent R
-#' list. Note that this is \code{as_list()}, not \code{as.list()}:
-#' \code{lapply()} automatically calls \code{as.list()} on its inputs, so
+#' list. Note that this is `as_list()`, not `as.list()`:
+#' `lapply()` automatically calls `as.list()` on its inputs, so
 #' we can't override the default.
 #'
-#' \code{as_list} currently only handles the four most common types of
+#' `as_list` currently only handles the four most common types of
 #' children that an element might have:
 #'
 #' \itemize{
 #'   \item Other elements, converted to lists.
 #'   \item Attributes, stored as R attributes. Attributes that have special meanings in R
-#'           (\code{\link{class}}, \code{\link{comment}}, \code{\link{dim}},
-#'           \code{\link{dimnames}}, \code{\link{names}}, \code{\link{row.names}} and
-#'           \code{\link{tsp}}) are escaped with '.'
+#'           ([class()], [comment()], [dim()],
+#'           [dimnames()], [names()], [row.names()] and
+#'           [tsp()]) are escaped with '.'
 #'   \item Text, stored as a character vector.
 #' }
 #'

R/classes.R

@@ -226,7 +226,7 @@ as.character.xml_missing <- function(x, ...) {
 `[[.xml_missing` <- function(x, i, ...) if (i == 1L) x else stop("subscript out of bounds")
 
 #' Construct a cdata node
-#' @param content The CDATA content, does not include \code{<![CDATA[}
+#' @param content The CDATA content, does not include `<![CDATA[`
 #' @examples
 #' x <- xml_new_root("root")
 #' xml_add_child(x, xml_cdata("<d/>"))
@@ -252,7 +252,7 @@ xml_comment <- function(content) {
 #'
 #' This is used to create simple document type definitions. If you need to
 #' create a more complicated definition with internal subsets it is recommended
-#' to parse a string directly with \code{read_xml()}.
+#' to parse a string directly with `read_xml()`.
 #' @param name The name of the declaration
 #' @param external_id The external ID of the declaration
 #' @param system_id The system ID of the declaration

R/utils.R

@@ -71,7 +71,7 @@ parse_options <- function(arg, options) {
 #'
 #' xml2 comes bundled with a number of sample files in its \sQuote{inst/extdata}
 #' directory. This function makes them easy to access.
-#' @param path Name of file. If \code{NULL}, the example files will be listed.
+#' @param path Name of file. If `NULL`, the example files will be listed.
 #' @export
 xml2_example <- function(path = NULL) {
   if (is.null(path)) {

R/xml_attr.R

@@ -1,21 +1,21 @@
 #' Retrieve an attribute.
 #'
-#' \code{xml_attrs()} retrieves all attributes values as a named character
-#' vector, \code{xml_attrs() <-} or \code{xml_set_attrs()} sets all attribute
-#' values. \code{xml_attr()} retrieves the value of single attribute and
-#' \code{xml_attr() <-} or \code{xml_set_attr()} modifies its value. If the
-#' attribute doesn't exist, it will return \code{default}, which defaults to
-#' \code{NA}. \code{xml_has_attr()} tests if an attribute is present.
+#' `xml_attrs()` retrieves all attributes values as a named character
+#' vector, `xml_attrs() <-` or `xml_set_attrs()` sets all attribute
+#' values. `xml_attr()` retrieves the value of single attribute and
+#' `xml_attr() <-` or `xml_set_attr()` modifies its value. If the
+#' attribute doesn't exist, it will return `default`, which defaults to
+#' `NA`. `xml_has_attr()` tests if an attribute is present.
 #'
 #' @inheritParams xml_name
 #' @param attr Name of attribute to extract.
 #' @param default Default value to use when attribute is not present.
-#' @return \code{xml_attr()} returns a character vector. \code{NA} is used
+#' @return `xml_attr()` returns a character vector. `NA` is used
 #'  to represent of attributes that aren't defined.
 #'
-#'  \code{xml_has_attr()} returns a logical vector.
+#'  `xml_has_attr()` returns a logical vector.
 #'
-#'  \code{xml_attrs()} returns a named character vector if \code{x} x is single
+#'  `xml_attrs()` returns a named character vector if `x` x is single
 #'  node, or a list of character vectors if given a nodeset
 #' @export
 #' @examples

R/xml_children.R

@@ -1,16 +1,16 @@
 #' Navigate around the family tree.
 #'
-#' \code{xml_children} returns only elements, \code{xml_contents} returns
-#' all nodes. \code{xml_length} returns the number of children.
-#' \code{xml_parent} returns the parent node, \code{xml_parents}
-#' returns all parents up to the root. \code{xml_siblings} returns all nodes
-#' at the same level. \code{xml_child} makes it easy to specify a specific
+#' `xml_children` returns only elements, `xml_contents` returns
+#' all nodes. `xml_length` returns the number of children.
+#' `xml_parent` returns the parent node, `xml_parents`
+#' returns all parents up to the root. `xml_siblings` returns all nodes
+#' at the same level. `xml_child` makes it easy to specify a specific
 #' child to return.
 #'
 #' @inheritParams xml_name
-#' @param only_elements For \code{xml_length}, should it count all children,
+#' @param only_elements For `xml_length`, should it count all children,
 #'   or just children that are elements (the default)?
-#' @param search For \code{xml_child}, either the child number to return (by
+#' @param search For `xml_child`, either the child number to return (by
 #'   position), or the name of the child node to return. If there are multiple
 #'   child nodes with the same name, the first will be returned
 #' @return A node or nodeset (possibly empty). Results are always de-duplicated.

R/xml_find.R

@@ -2,30 +2,30 @@
 #'
 #' Xpath is like regular expressions for trees - it's worth learning if
 #' you're trying to extract nodes from arbitrary locations in a document.
-#' Use \code{xml_find_all} to find all matches - if there's no match you'll
-#' get an empty result. Use \code{xml_find_first} to find a specific match -
-#' if there's no match you'll get an \code{xml_missing} node.
+#' Use `xml_find_all` to find all matches - if there's no match you'll
+#' get an empty result. Use `xml_find_first` to find a specific match -
+#' if there's no match you'll get an `xml_missing` node.
 #'
 #' @section Deprecated functions:
-#' \code{xml_find_one()} has been deprecated. Instead use
-#' \code{xml_find_first()}.
+#' `xml_find_one()` has been deprecated. Instead use
+#' `xml_find_first()`.
 
 #' @param xpath A string containing a xpath (1.0) expression.
 #' @inheritParams xml_name
-#' @return \code{xml_find_all} always returns a nodeset: if there are no matches
+#' @return `xml_find_all` always returns a nodeset: if there are no matches
 #'   the nodeset will be empty. The result will always be unique; repeated
 #'   nodes are automatically de-duplicated.
 #'
-#'   \code{xml_find_first} returns a node if applied to a node, and a nodeset
-#'   if applied to a nodeset. The output is \emph{always} the same size as
-#'   the input. If there are no matches, \code{xml_find_first} will return a
+#'   `xml_find_first` returns a node if applied to a node, and a nodeset
+#'   if applied to a nodeset. The output is *always* the same size as
+#'   the input. If there are no matches, `xml_find_first` will return a
 #'   missing node; if there are multiple matches, it will return the first
 #'   only.
 #'
-#'   \code{xml_find_num}, \code{xml_find_chr}, \code{xml_find_lgl} return
+#'   `xml_find_num`, `xml_find_chr`, `xml_find_lgl` return
 #'   numeric, character and logical results respectively.
 #' @export
-#' @seealso \code{\link{xml_ns_strip}} to remove the default namespaces
+#' @seealso [xml_ns_strip()] to remove the default namespaces
 #' @examples
 #' x <- read_xml("<foo><bar><baz/></bar><baz/></foo>")
 #' xml_find_all(x, ".//baz")

R/xml_modify.R

@@ -1,19 +1,19 @@
 #' Modify a tree by inserting, replacing or removing nodes
 #'
-#' \code{xml_add_sibling()} and \code{xml_add_child()} are used to insert a node
-#' as a sibling or a child. \code{xml_add_parent()} adds a new parent in
-#' between the input node and the current parent. \code{xml_replace()}
-#' replaces an existing node with a new node. \code{xml_remove()} removes a
+#' `xml_add_sibling()` and `xml_add_child()` are used to insert a node
+#' as a sibling or a child. `xml_add_parent()` adds a new parent in
+#' between the input node and the current parent. `xml_replace()`
+#' replaces an existing node with a new node. `xml_remove()` removes a
 #' node from the tree.
 #'
-#' @details Care needs to be taken when using \code{xml_remove()},
+#' @details Care needs to be taken when using `xml_remove()`,
 #' @param .x a document, node or nodeset.
-#' @param .copy whether to copy the \code{.value} before replacing. If this is \code{FALSE}
+#' @param .copy whether to copy the `.value` before replacing. If this is `FALSE`
 #'   then the node will be moved from it's current location.
-#' @param .where to add the new node, for \code{xml_add_child} the position
-#' after which to add, use \code{0} for the first child. For
-#' \code{xml_add_sibling} either \sQuote{"before"} or \sQuote{"after"}
-#' indicating if the new node should be before or after \code{.x}.
+#' @param .where to add the new node, for `xml_add_child` the position
+#' after which to add, use `0` for the first child. For
+#' `xml_add_sibling` either \sQuote{"before"} or \sQuote{"after"}
+#' indicating if the new node should be before or after `.x`.
 #' @param ... If named attributes or namespaces to set on the node, if unnamed
 #' text to assign to the node.
 #' @param .value node to insert.
@@ -282,23 +282,23 @@ xml_set_namespace <- function(.x, prefix = "", uri = "") {
 
 #' Create a new document, possibly with a root node
 #'
-#' \code{xml_new_document} creates only a new document without a root node. In
-#' most cases you should instead use \code{xml_new_root}, which creates a new
+#' `xml_new_document` creates only a new document without a root node. In
+#' most cases you should instead use `xml_new_root`, which creates a new
 #' document and assigns the root node in one step.
 #' @param version The version number of the document.
 #' @param encoding The character encoding to use in the document. The default
 #' encoding is \sQuote{UTF-8}. Available encodings are specified at
-#' \url{http://xmlsoft.org/html/libxml-encoding.html#xmlCharEncoding}.
-#' @return A \code{xml_document} object.
+#' <http://xmlsoft.org/html/libxml-encoding.html#xmlCharEncoding>.
+#' @return A `xml_document` object.
 #' @export
 # TODO: jimhester 2016-12-16 Deprecate this in the future?
 xml_new_document <- function(version = "1.0", encoding = "UTF-8") {
   doc <- doc_new(version)
   structure(list(doc = doc), class = "xml_document")
 }
 
-#' @param .version The version number of the document, passed to \code{xml_new_document(version)}.
-#' @param .encoding The encoding of the document, passed to \code{xml_new_document(encoding)}.
+#' @param .version The version number of the document, passed to `xml_new_document(version)`.
+#' @param .encoding The encoding of the document, passed to `xml_new_document(encoding)`.
 #' @inheritParams xml_add_child
 #' @rdname xml_new_document
 #' @export

R/xml_name.R

@@ -2,12 +2,12 @@
 #'
 #' @param x A document, node, or node set.
 #' @param ns Optionally, a named vector giving prefix-url pairs, as produced
-#'   by \code{\link{xml_ns}}. If provided, all names will be explicitly
-#'   qualified with the ns prefix, i.e. if the element \code{bar} is defined
-#'   in namespace \code{foo}, it will be called \code{foo:bar}. (And
+#'   by [xml_ns()]. If provided, all names will be explicitly
+#'   qualified with the ns prefix, i.e. if the element `bar` is defined
+#'   in namespace `foo`, it will be called `foo:bar`. (And
 #'   similarly for attributes). Default namespaces must be given an explicit
-#'   name. The ns is ignored when using \code{\link{xml_name<-}} and
-#'   \code{\link{xml_set_name}}.
+#'   name. The ns is ignored when using [xml_name<-()] and
+#'   [xml_set_name()].
 #' @return A character vector.
 #' @export
 #' @examples

R/xml_namespaces.R

@@ -1,16 +1,16 @@
 #' XML namespaces.
 #'
-#' \code{xml_ns} extracts all namespaces from a document, matching each
+#' `xml_ns` extracts all namespaces from a document, matching each
 #' unique namespace url with the prefix it was first associated with. Default
-#' namespaces are named \code{d1}, \code{d2} etc. Use \code{xml_ns_rename}
+#' namespaces are named `d1`, `d2` etc. Use `xml_ns_rename`
 #' to change the prefixes. Once you have a namespace object, you can pass it to
 #' other functions to work with fully qualified names instead of local names.
 #'
 #' @export
 #' @inheritParams xml_name
 #' @param old,... An existing xml_namespace object followed by name-value
 #'   (old prefix-new prefix) pairs to replace.
-#' @return A character vector with class \code{xml_namespace} so the
+#' @return A character vector with class `xml_namespace` so the
 #'   default display is a little nicer.
 #' @examples
 #' x <- read_xml('

R/xml_parse.R

@@ -3,9 +3,9 @@
 #' @param x A string, a connection, or a raw vector.
 #'
 #'   A string can be either a path, a url or literal xml. Urls will
-#'   be converted into connections either using \code{base::url} or, if
-#'   installed, \code{curl::curl}. Local paths ending in \code{.gz},
-#'   \code{.bz2}, \code{.xz}, \code{.zip} will be automatically uncompressed.
+#'   be converted into connections either using `base::url` or, if
+#'   installed, `curl::curl`. Local paths ending in `.gz`,
+#'   `.bz2`, `.xz`, `.zip` will be automatically uncompressed.
 #'
 #'   If a connection, the complete connection is read into a raw vector before
 #'   being parsed.
@@ -18,7 +18,7 @@
 #' @param base_url When loading from a connection, raw vector or literal
 #'   html/xml, this allows you to specify a base url for the document. Base
 #'   urls are used to turn relative urls into absolute urls.
-#' @param n If \code{file} is a connection, the number of bytes to read per
+#' @param n If `file` is a connection, the number of bytes to read per
 #'    iteration. Defaults to 64kb.
 #' @param verbose When reading from a slow connection, this prints some
 #'    output on every iteration so you know its working.
@@ -132,7 +132,7 @@ read_xml.response <- function(x, encoding = "", base_url = "", ...,
 #' @inherit curl::curl_download
 #' @param file A character string with the name where the downloaded file is
 #'   saved.
-#' @seealso \link[curl]{curl_download}
+#' @seealso [curl_download][curl::curl_download]
 #' @export
 #' @examples
 #' \dontrun{

R/xml_serialize.R

@@ -1,7 +1,7 @@
 #' Serializing XML objects to connections.
 #'
 #' @inheritParams base::serialize
-#' @param ... Additional arguments passed to \code{\link{read_xml}}.
+#' @param ... Additional arguments passed to [read_xml()].
 #' @inherit base::serialize return
 #' @examples
 #' library(xml2)

R/xml_structure.R

@@ -2,8 +2,8 @@
 #'
 #' Show the structure of an html/xml document without displaying any of
 #' the values. This is useful if you want to get a high level view of the
-#' way a document is organised. Compared to \code{xml_structure},
-#' \code{html_structure} prints the id and class attributes.
+#' way a document is organised. Compared to `xml_structure`,
+#' `html_structure` prints the id and class attributes.
 #'
 #' @param x HTML/XML document (or part there of)
 #' @param indent Number of spaces to ident