diff --git a/R/draft.R b/R/draft.R index f3ab28f..1e0f9ce 100644 --- a/R/draft.R +++ b/R/draft.R @@ -4,61 +4,58 @@ #' stock assessment document written with \pkg{sa4ss}. #' #' @details -#' ## Wrapper for [rmarkdown::draft] -#' The function is based on [rmarkdown::draft] that creates -#' new R Markdown documents based on templates stored within R packages. -#' The [rticles](https://github.com/rstudio/rticles) R package stores the -#' most templates, mainly for the submission of manuscripts to journals. +#' ## Wrapper for [rmarkdown::draft()] +#' The function is based on [rmarkdown::draft()] that creates new R Markdown +#' documents based on templates stored within R packages. The +#' [rticles](https://github.com/rstudio/rticles) R package stores the most +#' templates, mainly for the submission of manuscripts to journals. #' -#' User input for parameters such as `authors` and `species` help customize -#' the draft to your stock assessment document. Therefore, -#' users should focus on the input arguments that come before `type =` -#' because these will be specific to the stock assessment and are used to -#' set up the initial file structure. +#' User input for parameters such as `authors` and `species` help customize the +#' draft to your stock assessment document. Therefore, users should focus on +#' the input arguments that come before `type =` because these will be specific +#' to the stock assessment and are used to set up the initial file structure. #' #' ## File structure #' A template contains two mandatory objects, #' * template.yaml #' * skeleton/skeleton.Rmd, -#' and optional files include those in a directory named resources -#' and additional files within the skeleton directory. -#' Because it is not known what your directory will be named, the -#' skeleton file is renamed to `00a.Rmd` by this function to ensure that -#' it comes first in bookdown's rendering of all of the .Rmd files, -#' which is done alphabetically unless users specify all the files, -#' an option that we do not really want to use. +#' and optional files include those in a directory named resources and +#' additional files within the skeleton directory. Because it is not known what +#' your directory will be named, the skeleton file is renamed to `00a.Rmd` by +#' this function to ensure that it comes first in bookdown's rendering of all +#' of the .Rmd files, which is done alphabetically unless users specify all the +#' files, an option that we do not really want to use. #' #' @template authors #' @template species #' @template latin #' @template coast -#' @param type The name of the template you want to initiate. -#' The default template is `sa`, which stands for stock assessment. -#' As development for \pkg{sa4ss} progresses, expect to see more templates -#' become available. Available templates are listed in the default function call. -#' Specify a single character value from those available if you want to change -#' the type from the default. +#' @param type The name of the template you want to initiate. The default +#' template is `sa`, which stands for stock assessment. As development for +#' \pkg{sa4ss} progresses, expect to see more templates become available. +#' Available templates are listed in the default function call. Specify a +#' single character value from those available if you want to change the type +#' from the default. #' @param create_dir A logical value that leads to the draft document being -#' placed in its own directory called `"doc"`. -#' The default value of \code{FALSE} uses the current working directory -#' rather than containing all of the files in a new directory, -#' which is helpful if you want to use your own name for the directory. -#' \code{TRUE} will create the new directory `"doc"` and copy of the necessary -#' files into it. -#' A third option also exists, `"default"`, which allows [rmarkdown::draft], -#' to determine the appropriate directory structure. +#' placed in its own directory called `"doc"`. The default value of +#' \code{FALSE} uses the current working directory rather than containing all +#' of the files in a new directory, which is helpful if you want to use your +#' own name for the directory. \code{TRUE} will create the new directory +#' `"doc"` and copy of the necessary files into it. A third option also +#' exists, `"default"`, which allows [rmarkdown::draft()], to determine the +#' appropriate directory structure. #' @param edit A logical value, with a default of \code{FALSE}, specifying if -#' you want to open the indexing file for editing by default. The software chosen -#' by R is normally not ideal and -#' the file is not a file that is normally edited by users, -#' which is why \pkg{sa4ss} does not follow the default value used by -#' [rmarkdown::draft]. +#' you want to open the indexing file for editing by default. The software +#' chosen by R is normally not ideal and the file is not a file that is +#' normally edited by users, which is why \pkg{sa4ss} does not follow the +#' default value used by [rmarkdown::draft()]. #' @param ... Additional arguments that you wish to pass to -#' [rmarkdown::draft]. See `args(rmarkdown::draft)`. +#' [rmarkdown::draft()]. See `args(rmarkdown::draft)`. #' -#' @return Invisibly returns the file name of the document, -#' which will be the main indexing file that links to the auxiliary files. -#' If `edit = TRUE`, this file will be opened for editing. +#' @return +#' Invisibly returns the file name of the document, which will be the main +#' indexing file that links to the auxiliary files. If `edit = TRUE`, this file +#' will be opened for editing. #' @examples #' \dontrun{ #' sa4ss::draft() @@ -69,43 +66,43 @@ #' @author Kelli F. Johnson #' draft <- function(authors, - species = "Species name", - latin = "Scientific name", - coast = "US West", - type = c("sa"), - create_dir = FALSE, - edit = FALSE, - ...) { - type <- match.arg(type, several.ok = FALSE) + species = "Species name", + latin = "Scientific name", + coast = "U.S. West Coast", + type = c("sa"), + create_dir = FALSE, + edit = FALSE, + ...) { + type <- match.arg(type, several.ok = FALSE) - filename <- rmarkdown::draft( - file = "doc.Rmd", - template = type, - package = "sa4ss", - create_dir = create_dir, - edit = edit, - ... - ) + filename <- rmarkdown::draft( + file = "doc.Rmd", + template = type, + package = "sa4ss", + create_dir = create_dir, + edit = edit, + ... + ) - newname <- gsub("doc.Rmd", "00a.Rmd", filename) - file.rename(filename, newname) - thedir <- dirname(newname) - write_title( - species = species, latin = latin, coast = coast, - fileout = file.path(thedir, formals(write_title)$fileout) - ) - write_authors(authors, - fileout = file.path(thedir, formals(write_authors)$fileout) - ) - spp <- species - # Make the first letter of the first word capital Cannot use title case or - # sentence case because I do not want to change the case of the second word, - # only the first. - Spp <- stringr::str_replace(spp, "^\\w{1}", toupper) - spp.sci <- latin - save(spp, Spp, spp.sci, coast, authors, - file = file.path(thedir, "00opts.Rdata") - ) + newname <- gsub("doc.Rmd", "00a.Rmd", filename) + file.rename(filename, newname) + thedir <- dirname(newname) + write_title( + species = species, latin = latin, coast = coast, + fileout = file.path(thedir, formals(write_title)$fileout) + ) + write_authors(authors, + fileout = file.path(thedir, formals(write_authors)$fileout) + ) + spp <- species + # Make the first letter of the first word capital Cannot use title case or + # sentence case because I do not want to change the case of the second word, + # only the first. + Spp <- stringr::str_replace(spp, "^\\w{1}", toupper) + spp.sci <- latin + save(spp, Spp, spp.sci, coast, authors, + file = file.path(thedir, "00opts.Rdata") + ) - return(invisible(newname)) + return(invisible(newname)) } diff --git a/R/write_title.R b/R/write_title.R index 36f9bab..1d1e7db 100644 --- a/R/write_title.R +++ b/R/write_title.R @@ -29,7 +29,7 @@ write_title <- function(species, "---\n", yaml::as.yaml(list(title = paste0( "Status of ", species, " (_", latin, "_)", - " along the ", coast, " coast in ", year + " along the ", coast, " in ", year ))), "---" ), diff --git a/man/draft.Rd b/man/draft.Rd index e97b1e2..3561284 100644 --- a/man/draft.Rd +++ b/man/draft.Rd @@ -8,7 +8,7 @@ draft( authors, species = "Species name", latin = "Scientific name", - coast = "US West", + coast = "U.S. West Coast", type = c("sa"), create_dir = FALSE, edit = FALSE, @@ -41,59 +41,61 @@ beginning of a sentence.} italic formatting. Please capitalize as you want it to be used in the document though because case will not be altered.} -\item{coast}{A character string specifying which part of the coast -the stock assessment includes. For example, \code{"US West"}. -Do not include \code{"coast"} because it will be added internally.} +\item{coast}{A character string specifying which part of the coast the stock +assessment includes. For example, \code{"U.S. West Coast"}, which is the +default, will be used to create the following title: "Status of common +name (latin name) along the U.S. West Coast in 2010". Previously, the word +coast was added internally to the text, this is no longer the default +behavior of sa4ss and instead you must explicitly add the word, which +allows users to have more flexibility. For example, "California Coast from +Point Conception north" is a viable option.} -\item{type}{The name of the template you want to initiate. -The default template is \code{sa}, which stands for stock assessment. -As development for \pkg{sa4ss} progresses, expect to see more templates -become available. Available templates are listed in the default function call. -Specify a single character value from those available if you want to change -the type from the default.} +\item{type}{The name of the template you want to initiate. The default +template is \code{sa}, which stands for stock assessment. As development for +\pkg{sa4ss} progresses, expect to see more templates become available. +Available templates are listed in the default function call. Specify a +single character value from those available if you want to change the type +from the default.} \item{create_dir}{A logical value that leads to the draft document being -placed in its own directory called \code{"doc"}. -The default value of \code{FALSE} uses the current working directory -rather than containing all of the files in a new directory, -which is helpful if you want to use your own name for the directory. -\code{TRUE} will create the new directory \code{"doc"} and copy of the necessary -files into it. -A third option also exists, \code{"default"}, which allows \link[rmarkdown:draft]{rmarkdown::draft}, -to determine the appropriate directory structure.} +placed in its own directory called \code{"doc"}. The default value of +\code{FALSE} uses the current working directory rather than containing all +of the files in a new directory, which is helpful if you want to use your +own name for the directory. \code{TRUE} will create the new directory +\code{"doc"} and copy of the necessary files into it. A third option also +exists, \code{"default"}, which allows \code{\link[rmarkdown:draft]{rmarkdown::draft()}}, to determine the +appropriate directory structure.} \item{edit}{A logical value, with a default of \code{FALSE}, specifying if -you want to open the indexing file for editing by default. The software chosen -by R is normally not ideal and -the file is not a file that is normally edited by users, -which is why \pkg{sa4ss} does not follow the default value used by -\link[rmarkdown:draft]{rmarkdown::draft}.} +you want to open the indexing file for editing by default. The software +chosen by R is normally not ideal and the file is not a file that is +normally edited by users, which is why \pkg{sa4ss} does not follow the +default value used by \code{\link[rmarkdown:draft]{rmarkdown::draft()}}.} \item{...}{Additional arguments that you wish to pass to -\link[rmarkdown:draft]{rmarkdown::draft}. See \code{args(rmarkdown::draft)}.} +\code{\link[rmarkdown:draft]{rmarkdown::draft()}}. See \code{args(rmarkdown::draft)}.} } \value{ -Invisibly returns the file name of the document, -which will be the main indexing file that links to the auxiliary files. -If \code{edit = TRUE}, this file will be opened for editing. +Invisibly returns the file name of the document, which will be the main +indexing file that links to the auxiliary files. If \code{edit = TRUE}, this file +will be opened for editing. } \description{ Initiate a directory that contains all of the files needed for a stock assessment document written with \pkg{sa4ss}. } \details{ -\subsection{Wrapper for \link[rmarkdown:draft]{rmarkdown::draft}}{ +\subsection{Wrapper for \code{\link[rmarkdown:draft]{rmarkdown::draft()}}}{ -The function is based on \link[rmarkdown:draft]{rmarkdown::draft} that creates -new R Markdown documents based on templates stored within R packages. -The \href{https://github.com/rstudio/rticles}{rticles} R package stores the -most templates, mainly for the submission of manuscripts to journals. +The function is based on \code{\link[rmarkdown:draft]{rmarkdown::draft()}} that creates new R Markdown +documents based on templates stored within R packages. The +\href{https://github.com/rstudio/rticles}{rticles} R package stores the most +templates, mainly for the submission of manuscripts to journals. -User input for parameters such as \code{authors} and \code{species} help customize -the draft to your stock assessment document. Therefore, -users should focus on the input arguments that come before \verb{type =} -because these will be specific to the stock assessment and are used to -set up the initial file structure. +User input for parameters such as \code{authors} and \code{species} help customize the +draft to your stock assessment document. Therefore, users should focus on +the input arguments that come before \verb{type =} because these will be specific +to the stock assessment and are used to set up the initial file structure. } \subsection{File structure}{ @@ -102,13 +104,12 @@ A template contains two mandatory objects, \itemize{ \item template.yaml \item skeleton/skeleton.Rmd, -and optional files include those in a directory named resources -and additional files within the skeleton directory. -Because it is not known what your directory will be named, the -skeleton file is renamed to \verb{00a.Rmd} by this function to ensure that -it comes first in bookdown's rendering of all of the .Rmd files, -which is done alphabetically unless users specify all the files, -an option that we do not really want to use. +and optional files include those in a directory named resources and +additional files within the skeleton directory. Because it is not known what +your directory will be named, the skeleton file is renamed to \verb{00a.Rmd} by +this function to ensure that it comes first in bookdown's rendering of all +of the .Rmd files, which is done alphabetically unless users specify all the +files, an option that we do not really want to use. } } } diff --git a/man/roxygen/templates/coast.R b/man/roxygen/templates/coast.R index 40dd3eb..bebae8c 100644 --- a/man/roxygen/templates/coast.R +++ b/man/roxygen/templates/coast.R @@ -1,3 +1,8 @@ -#' @param coast A character string specifying which part of the coast -#' the stock assessment includes. For example, \code{"US West"}. -#' Do not include \code{"coast"} because it will be added internally. +#' @param coast A character string specifying which part of the coast the stock +#' assessment includes. For example, `"U.S. West Coast"`, which is the +#' default, will be used to create the following title: "Status of common +#' name (latin name) along the U.S. West Coast in 2010". Previously, the word +#' coast was added internally to the text, this is no longer the default +#' behavior of sa4ss and instead you must explicitly add the word, which +#' allows users to have more flexibility. For example, "California Coast from +#' Point Conception north" is a viable option. diff --git a/man/write_title.Rd b/man/write_title.Rd index adde091..40aeb37 100644 --- a/man/write_title.Rd +++ b/man/write_title.Rd @@ -28,9 +28,14 @@ beginning of a sentence.} italic formatting. Please capitalize as you want it to be used in the document though because case will not be altered.} -\item{coast}{A character string specifying which part of the coast -the stock assessment includes. For example, \code{"US West"}. -Do not include \code{"coast"} because it will be added internally.} +\item{coast}{A character string specifying which part of the coast the stock +assessment includes. For example, \code{"U.S. West Coast"}, which is the +default, will be used to create the following title: "Status of common +name (latin name) along the U.S. West Coast in 2010". Previously, the word +coast was added internally to the text, this is no longer the default +behavior of sa4ss and instead you must explicitly add the word, which +allows users to have more flexibility. For example, "California Coast from +Point Conception north" is a viable option.} \item{year}{A numeric or character string specifying the year. The default uses \code{\link[=Sys.Date]{Sys.Date()}} to format the year into a four digit character value.}