finalise v2.6

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: Rdpack
 Type: Package
 Title: Update and Manipulate Rd Documentation Objects
-Version: 2.5.9000
+Version: 2.6
 Authors@R: c( person(given = c("Georgi", "N."),
                      family = "Boshnakov", 
                      role = c("aut", "cre"), 

NEWS.md

@@ -1,3 +1,16 @@
+# Rdpack 2.6
+
+- fixed issues causing 'lost braces' (actually, superfluous braces) NOTEs from
+  checks in R-devel occuring with some accented LaTeX characters. These NOTEs
+  are not yet activated on CRAN but if/when they do, developers using Rd macros
+  `\insertRef` and `\insertCite` can eliminate them by building their packages
+  with Rdpack (> 2.5) and rbibutils (>= 2.2.16).  Thanks to Sebastian Meyer for
+  tracing down the issues.
+
+- fixed a `Sweave` expression in 'man/predefined.Rd' to not emit unnecessary
+  braces (see the note above).
+
+
 # Rdpack 2.5
 
 - Rd macros `insertCite` and friends were calling `insert_citeOnly` with

R/bib.R

@@ -1052,49 +1052,50 @@ insert_all_ref <- function(refs, style = "", empty_cited = FALSE){
     paste0(res, collapse = "\\cr\\cr ")
 }
 
-deparseLatexToRd <- function(x, dropBraces = FALSE)
-{
-    result <- character()
-    lastTag <- "TEXT"
-    for (i in seq_along(x)) {
-        a <- x[[i]]
-        tag <- attr(a, "latex_tag")
-        if (is.null(tag)) tag <- "NULL"
-        switch(tag,
-        VERB = ,
-        TEXT = ,
-        COMMENT = result <- c(result, a),
-        MACRO = {
-            ## see issue #26
-            ## regex in r-devel/R/src/library/tools/R/RdConv2.R:
-            ##     pat <- "([^\\]|^)\\\\[#$&_^~]"
-            ## here we add grouping for substitution
-            pat <- "([^\\]|^)(\\\\)([#$&_^~])"  # with more grouping
-            if(grepl(pat, a)){
-                a <- gsub(pat, "\\1\\3", a)
-            }
-            result <- c(result, a)
-        },
-        BLOCK = result <- c(result, if (dropBraces && lastTag == "TEXT") Recall(a) else c("{", Recall(a), "}")),
-        ENVIRONMENT = result <- c(result,
-        	"\\begin{", a[[1L]], "}",
-        	Recall(a[[2L]]),
-        	"\\end{", a[[1L]], "}"),
-        ## MATH = result <- c(result, "$", Recall(a), "$"),
-        MATH = result <- c(result, "\\eqn{", Recall(a), "}"),
-        NULL = stop("Internal error, no tag", domain = NA)
-        )
-        lastTag <- tag
-    }
-    paste(result, collapse="")
-}
-
-
+## deparseLatexToRd <- function(x, dropBraces = FALSE)
+## {
+##     result <- character()
+##     lastTag <- "TEXT"
+##     for (i in seq_along(x)) {
+##         a <- x[[i]]
+##         tag <- attr(a, "latex_tag")
+##         if (is.null(tag)) tag <- "NULL"
+##         switch(tag,
+##         VERB = ,
+##         TEXT = ,
+##         COMMENT = result <- c(result, a),
+##         MACRO = {
+##             ## see issue #26
+##             ## regex in r-devel/R/src/library/tools/R/RdConv2.R:
+##             ##     pat <- "([^\\]|^)\\\\[#$&_^~]"
+##             ## here we add grouping for substitution
+##             pat <- "([^\\]|^)(\\\\)([#$&_^~])"  # with more grouping
+##             if(grepl(pat, a)){
+##                 a <- gsub(pat, "\\1\\3", a)
+##             }
+##             result <- c(result, a)
+##         },
+##         BLOCK = result <- c(result, if (dropBraces && lastTag == "TEXT") Recall(a) else c("{", Recall(a), "}")),
+##         ENVIRONMENT = result <- c(result,
+##         	"\\begin{", a[[1L]], "}",
+##         	Recall(a[[2L]]),
+##         	"\\end{", a[[1L]], "}"),
+##         ## MATH = result <- c(result, "$", Recall(a), "$"),
+##         MATH = result <- c(result, "\\eqn{", Recall(a), "}"),
+##         NULL = stop("Internal error, no tag", domain = NA)
+##         )
+##         lastTag <- tag
+##     }
+##     paste(result, collapse="")
+## }
 
 `%notin%` <-
 function(x, y)
     is.na(match(x, y))
 
+## tools::deparseLatex() is by Sebastian Meyer and Duncan Murdoc. Below is a
+## version suitable for Rdpack.
+##
 ## This converts a latex object into a single element character vector
 deparseLatexToRd <- function(x, dropBraces = FALSE)
 {

man/Rdpack-package.Rd

@@ -280,7 +280,7 @@ R 3.6.0.
 
 \verb{\printExample} is typically placed in section Details of an
 object's documentation, see section Details of \code{\link{get_usage}}
-for anumber of examples produced mostly with \verb{\printExample}.
+for a number of examples produced mostly with \verb{\printExample}.
 
 The macro \verb{\runExamples} can be used as a replacement
 of section \verb{Examples}.

man/Rdpack_bibstyles.Rd

@@ -1,25 +1,28 @@
 \name{Rdpack_bibstyles}
 \alias{Rdpack_bibstyles}
-%- Also NEED an '\alias' for EACH other topic documented here.
+
 \title{Set up a custom style for references in help pages}
+
 \description{Set up a custom style for references in help pages.}
+
 \usage{
 Rdpack_bibstyles(package, authors)
 }
-%- maybe also 'usage' for other objects documented here.
+
 \arguments{
   \item{package}{the name of a package, a character string.}
   \item{authors}{if equal to "LongNames", use full names of authors in
     reference lists, see Details.}
 }
+
 \details{
 
   This is the initial implementation of support for styles for lists of
   bibliography references.
 
-  Currently setting "authors" to "LongNames" will cause the references
-  to appear with full names, eg John Smith rather than in the default
-  Smith J style. 
+  Currently setting \code{authors} to \code{"LongNames"} will cause the
+  references to appear with full names, eg John Smith rather than in the
+  default Smith J style.
 
   Package authors can request this feature by adding the following line
   to their \code{.onLoad} function (if their package has one):

man/insert_all_ref.Rd

@@ -37,16 +37,16 @@ insert_all_ref(refs, style = "", empty_cited = FALSE)
 
 }
 \value{
-  for \code{insert_all_ref}, a character string containing a textual
-  representation of the references, suitable for inclusion in an Rd
-  file 
+  a character string containing a textual representation of the
+  references, suitable for inclusion in an Rd file
 }
 \references{
-  Currently there are no citations. Nevethelese, I have put
-  \verb{\insertAllCited{}} just after this paragraph to show the message
-  that it prints when there are no citations. This seems better than
-  printing nothing but it may be argued also that there should be a
-  warning as well.
+
+  Currently there are no citations on this help page. Nevetheless, I
+  have put \verb{\insertAllCited{}} just after this paragraph to show
+  the message that it prints when there are no citations. This seems
+  better than printing nothing but it may be argued also that there
+  should be a warning as well.
 
   \insertAllCited{}
 }
@@ -75,4 +75,3 @@ m <- matrix(c("*", "Rdpack",  "*", "rbibutils"), ncol = 2, byrow = TRUE)
 cat(insert_all_ref(m), "\n")
 }
 \keyword{documentation}
-% use one of  RShowDoc("KEYWORDS")

man/insert_citeOnly.Rd

@@ -1,12 +1,16 @@
 \name{insert_citeOnly}
 \alias{insert_citeOnly}
+
 \title{Generate citations from bibtex keys}
+
 \description{Generate citations from bibtex keys.}
+
 \usage{
 insert_citeOnly(keys, package = NULL, before = NULL, after = NULL,
                 bibpunct = NULL, ..., cached_env = NULL,
                 cite_only = FALSE, dont_cite = FALSE)
 }
+
 \arguments{
   \item{keys}{
 
@@ -15,7 +19,8 @@ insert_citeOnly(keys, package = NULL, before = NULL, after = NULL,
     Rd macro \verb{\\insertCite}. Put \verb{;textual} at the end of the
     string to get a textual citation. Similarly, \verb{;nobrackets}
     requests parenthesised citation without the enclosing parentheses.
-
+    Alternatively, \code{keys} can contain one or more keys, separated
+    by commas.
   }
   \item{package}{name of an R package.}
   \item{before}{see \code{\link{citeNatbib}}.}
@@ -26,23 +31,27 @@ insert_citeOnly(keys, package = NULL, before = NULL, after = NULL,
   \item{cite_only}{for internal use.}
   \item{dont_cite}{for internal use.}
 }
+
 \details{
 
   This is the function behind \verb{\\insertCite} and related macros.
   Argument \code{"keys"} has the syntax of the first argument of
-  \verb{\\insertCite}.
+  \verb{\\insertCite}, see \code{\link{insertRef}} for full details.
 
 }
+
 \value{
   a character vector containing the references with Rd markup
 }
 %\references{
 %%% ~put references to the literature/web site here ~
 %}
 \author{Georgi N. Boshnakov}
+
 \seealso{
   \code{\link{insert_ref}} for description of all available Rd macros
 }
+
 \examples{
 insert_citeOnly("@see also @Rpackage:rbibutils and @parseRd", package = "Rdpack")
 ## (see also Boshnakov and Putman 2020 and Murdoch 2010)
@@ -55,4 +64,6 @@ insert_citeOnly("@see also @Rpackage:rbibutils and @parseRd;textual",
   package = "Rdpack")
 ## see also Boshnakov and Putman (2020) and Murdoch (2010)
 }
+
 \keyword{documentation}
+

man/insert_ref.Rd

@@ -1,7 +1,14 @@
 \name{insert_ref}
 \alias{insert_ref}
+
 \alias{insertRef}
+
+\concept{Rd macros}
+\concept{bibtex}
+
+
 \title{Insert bibtex references in Rd and roxygen2 documentation}
+
 \description{
 
   Package Rdpack provides Rd macros for inserting references and
@@ -11,9 +18,11 @@
   see the vignette.
 
 }
+
 \usage{
 insert_ref(key, package = NULL, \dots, cached_env = NULL)
 }
+
 \arguments{
   \item{key}{the bibtex key of the reference, a character string.}
   \item{package}{the package in which to look for the bibtex file.}
@@ -23,10 +32,11 @@ insert_ref(key, package = NULL, \dots, cached_env = NULL)
     "REFERENCES.bib", see \code{\link{get_bibentries}}.
   }
   \item{cached_env}{
-    environment, used to avoid repeatedly pasing the bib
-    file from scratch, mainly useful by the Rd macros.
+    environment, used to avoid repeatedly passing the bib
+    file from scratch, mainly used by the Rd macros.
   }
 }
+
 \details{
 
   \code{insert_ref} extracts a bibliograhic reference from a bibtex

man/predefined.Rd

@@ -2,6 +2,7 @@
 \alias{Rdo_predefined_sections}
 \alias{Rdo_piece_types}
 \alias{rdo_top_tags}
+
 \title{
   Tables of predefined sections and types of pieces of Rd objects
 }
@@ -21,8 +22,8 @@ rdo_top_tags
   \insertCite{parseRd}{Rdpack}. \pkg{Rdpack} stores them in the
   variables described here.
 
-  \code{Rdo_predefined_sections} is a named character vector of types of the
-  top level sections of an Rd object. 
+  \code{Rdo_predefined_sections} is a named character vector providing
+  the types of the top level sections in an Rd object.
 
   \code{Rdo_piece_types} is a named character vector giving the types of
   the core (all possible?)  Rd macros.
@@ -36,9 +37,8 @@ rdo_top_tags
 \value{
 
   for \code{Rdo_predefined_sections}, the name-value pairs are given in
-  the following table. For example,
-  \code{Rdo_predefined_sections["examples"]} is
-  \Sexpr[stage=build,results=rd]{Rdo_predefined_sections["examples"]}.
+  the following table. For example, \code{Rdo_predefined_sections["examples"]} results
+  in \Sexpr[stage=build,results=rd]{Rdo_predefined_sections["examples"]}.
 
   \Sexpr[stage=build,results=rd]{require(Rdpack);
     paste(
@@ -88,12 +88,12 @@ rdo_top_tags
 
   \Sexpr[stage=build,results=rd]{
     paste("\\\\tabular{lllll}{",
-    paste(sub("^[#]", "\\\\\\\\verb{#}", sub("^([\\\\])", "{\\\\\\\\\\\\1}", rdo_top_tags)),
+    paste(sub("^[#]", "\\\\\\\\verb{#}", sub("^([\\\\])", "\\\\\\\\\\\\1", rdo_top_tags)),
           c(rep("\\\\tab ",4),"\\\\cr"),
           sep="", collapse="\n"),
           "}")}
 
-  Note that most, but not all,  are prefixed with backaslash.
+  Note that most, but not all,  are prefixed with a backslash.
 }
 \references{
   \insertAllCited{}