forked from ismayc/thesisdown
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
145 lines (93 loc) · 8.73 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
---
output: github_document
---
<!-- README.md is generated from README.Rmd via `devtools::build_readme()`. Please edit README.Rmd -->
```{r include=FALSE}
knitr::opts_chunk$set(
fig.path = "man/figures/"
)
```
# dtsldown <img src="man/figures/dtsldown_hex.png" align="right" width=200 />
<!-- badges: start -->
[](https://github.com/digatus-fwd/dtsldown/actions)
<!-- badges: end -->
*Create 21st century documentation for digatus Technical Standards Library*
This project was inspired by the [reedtemplates](https://github.com/digatus-fwd/reedtemplates) package which in turn is based on [bookdown](https://github.com/rstudio/bookdown).
Currently, the PDF, bs4_book and gitbook versions are fully-functional. The Word version has a basic template assigned. Lastly, the ePub version is developmental, has no templates behind it, and essentially calls the appropriate functions in bookdown.
If you are new to working with `bookdown`/`rmarkdown`, please read over the documentation available in the `gitbook` template at <https://digatus-fwd.github.io/dtsldown_gitbook/>.
The current output for the four versions is here:
- [PDF](https://github.com/digatus-fwd/dtsldown/blob/main/dtsl.pdf) (Generating LaTeX file is available [here](https://github.com/digatus-fwd/dtsldown/blob/main/dtsl.tex) with other files in the [book directory](https://github.com/digatus-fwd/dtsldown/tree/main).)
- [Word](https://github.com/digatus-fwd/dtsldown/blob/main/dtsl.docx)
- [ePub](https://github.com/digatus-fwd/dtsldown/blob/main/dtsl.epub)
- [gitbook](https://digatus-fwd.github.io/dtsldown_gitbook)
- [bs4_book](https://digatus-fwd.github.io/dtsldown_book)
Under the hood, the digatus DTSL LaTeX template is used to ensure that documents conform precisely to submission standards. At the same time, composition and formatting can be done using lightweight [markdown](https://rmarkdown.rstudio.com/authoring_basics.html) syntax, and **R** code and its output can be seamlessly included using [rmarkdown](https://rmarkdown.rstudio.com).
### Using dtsldown from GitHub
Using {dtsldown} has some prerequisites which are described below. To compile PDF documents using **R**, you are going to need to have LaTeX installed. By far the easiest way to install LaTeX on any platform is with the [tinytex](https://yihui.name/tinytex/) R package:
```r
install.packages(c('tinytex', 'rmarkdown'))
tinytex::install_tinytex()
# after restarting RStudio, confirm that you have LaTeX with
tinytex:::is_tinytex()
```
You may need to install a few extra LaTeX packages on your first attempt to knit as well. Here is one such example of how to do so:
```r
tinytex::tlmgr_install("babel-portuges")
```
To use {dtsldown} from [RStudio](https://www.rstudio.com/products/rstudio/download/):
1. Ensure that you have already installed LaTeX and the fonts described above, and are using the latest version of [RStudio](https://www.rstudio.com/products/rstudio/download/). You can use `dtsldown` without RStudio. For example, you can write the Rmd files in your favorite text editor (e.g. [Atom](https://atom.io/), [Notepad++](https://notepad-plus-plus.org/)). But RStudio is probably the easiest tool for writing both R code and text in your documentation. It also provides a nice way to build your documentation while editing. We'll proceed assuming that you have decided to use the RStudio workflow.
2. Install the {bookdown} and {dtsldown} packages. Note that {dtsldown} is not available on CRAN at the moment and that's why `install.packages("dtsldown")` won't work. Use `remotes::install_github()` as shown below instead to install the package.
```r
if (!require("remotes"))
install.packages("remotes", repos = "https://cran.rstudio.org")
remotes::install_github("rstudio/bookdown")
remotes::install_github("digatus-fwd/dtsldown")
```
Note that you may need to restart RStudio at this point for the following dialog to show up.
3. Get started with the {dtsldown} template. There are two
options for doing so.
- 3a) **RECOMMENDED** Create a new RStudio project with a
{dtsldown} template.
In RStudio, click on **File** > **New Project** >
**New Directory**. Then select
**DTSL Project using dtsldown** from the dropdown that
will look something like the image below. You'll see the
graduation cap as the icon on the left for the appropriate
project type.
Next, give your project a name and specify where you'd like
the files to appear. In the screenshot below, the project
name is `my_dtsl` and it will appear as a new folder
on my Desktop.
If you got this far, skip over step 3b which is the older
version of getting the template. It might force you to
change some of the directories to get knitting to work
and has some other limitations as well. That's why step 3a
is recommended.
- 3b) Use the **New R Markdown** dialog to select **DTSL**:
Note that this will currently only **Knit** if you name the directory `index` as shown above. This guarantees that `index.html` is generated correctly for the bs4_book or Gitbook version of the documentation.
4. After choosing which type of output you'd like in the YAML at the top of `index.Rmd`, **Knit** the `index.Rmd` file to get the book in PDF, Word HTML formats.
### Day-to-day writing of your documentation
You need to edit the individual chapter R Markdown files to write your documentation. It's recommended that you version control your documentation using GitHub if possible. RStudio can also easily sync up with GitHub to make the process easier. While writing, you should `git commit` your work frequently, after every major activity on your documentation. For example, every few paragraphs or section of text, and after major step of analysis development. You should `git push` at the end of each work session before you leave your computer or change tasks. For a gentle, novice-friendly guide to getting starting with using Git with R and RStudio, see <https://happygitwithr.com/>.
## Rendering
To render your documentation into a PDF, open `index.Rmd` in RStudio and then click the "knit" button. To change the output formats between PDF, bs4_book, gitbook and Word, look at the `output:` field in `index.Rmd` and comment-out the formats you don't want.
The PDF file of your documentation will be deposited in the `_book/` directory, by default.
## Components
The following components are ones you should edit to customize your documentation:
### `_bookdown.yml`
This is the main configuration file for your documentation. You can change the name of your outputted file here for your documentation and other options about your documentation here.
### `index.Rmd`
This file contains all the meta information that goes at the beginning of your
document. You'll need to edit the top portion of this file (the YAML) to put your name on the first page, the title of your documentation, etc. Note that you need to have at least one chapter start in the `index.Rmd` file for the build to work. For the template, this is done with `# Introduction` in the example from the template.
### `01-chap1.Rmd`, `02-chap2.Rmd`, etc.
These are the `.Rmd` files for each chapter in your dissertation. Write your documentation in these. If you're writing in RStudio, you may find the [wordcount addin](https://github.com/benmarwick/wordcountaddin) useful for getting word counts and readability statistics in R Markdown documents.
### `bib/`
Store your bibliography (as bibtex files) here. We recommend using the [citr addin](https://github.com/crsh/citr) and [Zotero](https://www.zotero.org/) to efficiently manage and insert citations.
**Working with citations may be considered optional.** The purpose of digatus Technical Standards documentation is different from academic writing. You should rather concentrate on inlcuding other references that might be interesting to the reader to get more details about your content so s/he will be able to better understand what you're saying. Overall you would likely avoid repeating too many details that could be expexted professional knowledge.
### `csl/`
Specific style files for bibliographies should be stored here. A good source for
citation styles is https://github.com/citation-style-language/styles#readme.
### `figure/` and `data/`
Store your figures and data here and reference them in your R Markdown files. See the [bookdown book](https://bookdown.org/yihui/bookdown/) for details on cross-referencing items using R Markdown.