csasdown is an R package that uses the bookdown package to generate Canadian Science Advisory Secretariat (CSAS) documents in PDF or Word format using R Markdown. It is based on Chester Ismay's thesisdown package and Ben Marwick's huskydown package.
Slides from a recent workshop on csasdown [PDF].
To compile PDF documents using R, you need to have Pandoc, LaTeX and several related packages installed. If you have a recent version of RStudio, then you already have Pandoc.
- You will need to install LaTeX:
install.packages("tinytex")
tinytex::install_tinytex()- Install the csasdown package:
# install.packages("devtools")
devtools::install_github("pbs-assess/csasdown")-
Start a new project directory if you'd like. If you're using RStudio: File -> New Project. Open the RStudio project or set your R working directory to the root folder of the project. Create a new sub-directory and change your working directory to that folder first if that is where you want the report files.
-
Run this line in your R console to create a new Research Document from the built-in template in whatever your working directory is:
csasdown::draft("resdoc")You can do the same for a Technical Report:
csasdown::draft("techreport")or for a Science Response:
csasdown::draft("sr")You need to edit the individual chapter R Markdown files to write your report. While writing, you should git commit your work frequently. For a gentle novice-friendly guide to getting starting with using Git with R and RStudio, see http://happygitwithr.com/.
To render your report into a PDF or Word document, open index.Rmd in RStudio and then click the "knit" button:
To change the output formats between PDF and Word look at the output: field in index.Rmdand comment out the format you don't want.
Alternatively, if you're not using RStudio, you can run this from the R console, assuming your have set the main directory (the one with the index.Rmd file) as your working directory:
bookdown::render_book("index.Rmd")The rendered PDF or Word file of your report will be deposited in the _book/ directory.
If you want to add a CSAS-formatted .docx title page to a Res Doc, edit the file templates/RES2016-eng-titlepage.docx as desired and run the command:
csasdown::add_resdoc_docx_titlepage()This will attach the title page to the beginning of the Word document.
The following components are ones you should edit to customize your report:
This is the main configuration file for your report. It determines what .Rmd files are included in the output, and in what order. Arrange the order of your chapters in this file and ensure that the names match the names in your folders. If you add new sections, add them here.
This file contains all the meta information that goes at the beginning of your document. You'll need to edit this to put your name on the first page, add the title of your report, etc.
These are the .Rmd files for each chapter/section of your report. Write your report in these.
Store your bibliography (as BibTeX files) here. You might look at the citr addin and Zotero to efficiently manage and insert citations.
Style files for bibliographies should be stored here. You will want to use the included csas.csl, which is based on the CJFAS (Canadian Journal of Fisheries and Aquatic Sciences) .csl file.
Store pre-made figures and data here and reference them in your R Markdown files. See the bookdown book for details on cross-referencing items using R Markdown.
This contains any .docx or .tex files that are need to compile the documents. With the exception of the title page file, you shouldn't have to edit any of these files.
This project has drawn directly on code and ideas in the following:
If you would like to contribute to this project, please start by reading our Guide to Contributing. Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.