README.md 6.06 KB
Newer Older
lorenzwalthert's avatar
lorenzwalthert committed
1
2
3
4
5
6
7
8

<!-- README.md is generated from README.Rmd. Please edit that file -->

# A few words from the authors

This repository is a bookdown template, derived from the LaTeX template
from the semiar for statistics, ETH Zurich.

lorenzwalthert's avatar
lorenzwalthert committed
9
10
**How bookdown works**

lorenzwalthert's avatar
lorenzwalthert committed
11
In a nutshell, bookdown works as follows:
lorenzwalthert's avatar
lorenzwalthert committed
12
13
14
15
16
17

  - use knitr to convert Rmd to markdown.
  - use pandoc to convert markdown to latex, pdf, word, html books (with
    featuers like font size, background selection, full text search
    etc), epub.

lorenzwalthert's avatar
lorenzwalthert committed
18
19
20
21
22
23
The basic workflow is as follows:

  - Change a source file: In our template, the source of the body of the
    thesis is under `./rmd/`. For example, change `02-features.Rmd`
  - Re-compile the book using Cmd + Shift + B (for build) on a Mac and
    Ctrl + Shift + B on Windows / Linux.
lorenzwalthert's avatar
lorenzwalthert committed
24
25
26
  - You can customize the build in the RStudio Build Tab, where you can
    specify which output (html, pdf, etc.) you want to generate. This is
    remembered for the next build you are doing.s
lorenzwalthert's avatar
lorenzwalthert committed
27

lorenzwalthert's avatar
lorenzwalthert committed
28
29
30
**Why using bookdown**

The advantages of using bookdown instead of plain LaTeX are, in the eyes
lorenzwalthert's avatar
lorenzwalthert committed
31
of the creator of this template:
lorenzwalthert's avatar
lorenzwalthert committed
32
33
34
35
36
37
38
39
40

  - Generalization. Not just latex or PDF output, but any output
    supported by Pandoc.
  - The best of two worlds. Use intuitive markdown syntax where
    possible, use the full power of LaTeX syntax where needed. This
    includes a real-time latex equation previewer in RStudio, bibtex
    reference, LaTeX cross-, text- and figure reference.
  - It’s native R. Integrate R code and R output in your writing has
    never been easier than with bookdown. You can also use other
lorenzwalthert's avatar
lorenzwalthert committed
41
    languages supported by knitr such as python, stan etc.\[1\]
lorenzwalthert's avatar
lorenzwalthert committed
42
43
44

**How this template works**

lorenzwalthert's avatar
lorenzwalthert committed
45
There are different directories in this template:
lorenzwalthert's avatar
lorenzwalthert committed
46
47

``` bash
lorenzwalthert's avatar
lorenzwalthert committed
48
tree -d -L 2 --charset unicode
lorenzwalthert's avatar
lorenzwalthert committed
49
#> .
lorenzwalthert's avatar
lorenzwalthert committed
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
#> |-- _book
#> |   |-- figures
#> |   |-- libs
#> |   |-- man
#> |   `-- thesis_SfS_files
#> |-- _bookdown_files
#> |   `-- thesis_SfS_files
#> |-- bib
#> |-- figure
#> |-- figures
#> |-- images
#> |   `-- auto
#> |-- pdf
#> |-- rmd
#> |-- style
#> `-- tex
lorenzwalthert's avatar
lorenzwalthert committed
66
#> 
lorenzwalthert's avatar
lorenzwalthert committed
67
#> 16 directories
lorenzwalthert's avatar
lorenzwalthert committed
68
69
```

lorenzwalthert's avatar
lorenzwalthert committed
70
71
  - \_book: Contains the compiled book, e.g. a PDF or html version.
  - \_bib: Contains BibTeX reference data bases.
lorenzwalthert's avatar
lorenzwalthert committed
72
73
  - figure: Contains figures you created from your (R) code in the rmd
    source.
lorenzwalthert's avatar
lorenzwalthert committed
74
75
76
  - images: Put images you want to include in your thesis in this
    folder.
  - pdf: Put PDFs you want to include in your thesis in this folder.
lorenzwalthert's avatar
lorenzwalthert committed
77
78
79
80
  - rmd: The source folder of thesis. When you build a book, the
    following happens: By default, all rmd files in this folder get
    merged into one big rmd file, according to their name. We suggest to
    use one file per chapter. Then, the file containing all the rmd
lorenzwalthert's avatar
lorenzwalthert committed
81
    sources will get processed by knitr and later by Pandoc.
lorenzwalthert's avatar
lorenzwalthert committed
82
83
84
85
86
87
88
89
  - style: Latex .sty files. Taken from the sfs LaTeX template.
  - tex: All tex data, most importantly, the sfs LaTeX template itself.
    Note that the abstract, preface, epilogue, summary, notation are
    still in tex, i.e. you need to change these files if you want the
    PDF output to change. This will **not** affect the html output. You
    can create chapters that show up in a particular output and not in
    the other forms as shown in `rmd/99-references.Rmd`.

lorenzwalthert's avatar
lorenzwalthert committed
90
91
92
Furthermore, we want to highlight a few files in the root directory of
the project:

lorenzwalthert's avatar
lorenzwalthert committed
93
  - `DESCRIPTION`: You can use it to declare dependent packages of your
lorenzwalthert's avatar
lorenzwalthert committed
94
95
    thesis in the `Imports:` field. If someone want’s to rebuild you
    thesis from scratch, the can use `remotes::install_deps()` to
lorenzwalthert's avatar
lorenzwalthert committed
96
    satisfy all R package dependencies.
lorenzwalthert's avatar
lorenzwalthert committed
97
98
99
100
  - `index.Rmd`: Contains a YAML header where a few important variables
    are defined. You can also put markdown below the header.
  - `README.(R)md`: This document.
  - `thesis-template-bookdown.Rproj`: An RStudio project. We recommend
lorenzwalthert's avatar
lorenzwalthert committed
101
102
    using RStudio for authoring your master thesis with bookdown.

lorenzwalthert's avatar
lorenzwalthert committed
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
**A few recommendations**

  - We strongly suggest to use a different folder for the data / code of
    your thesis and reserve this directory for the thesis document only.
    You can reaname this directory `analysis-communication` (since this
    will be the means used for communicating the results and process of
    your thesis) and use `analysis-raw` for the code and `data` for all
    data. Ideally, you place them in the same directory so you can still
    work with relative paths, e.g. `../data`.
  - We suggest to use git version control for the thesis and the raw
    analsyis.
  - If your thesis is open source, you can use netlify.com to deploy it,
    i.e. for every commit you push to a remote repo like GitHub, you can
    use netlify’s CLI to build your book on a CI machine like travis.
    See file `travis.yml` for the bookdown book [Advanced
    R](https://github.com/hadley/adv-r/tree/88dcb07e2b2ae634af6cdeafff2f3ea976077064)
    for an example. That makes tracking the `_book` folder in git
    redundant.

**Further material**

lorenzwalthert's avatar
lorenzwalthert committed
124
125
126
127
This is obviously a very short introduction to the template and it is in
no way comprehensive. To learn more about bookdown, we encourage the
reader to have a look at the [bookdown
guide](https://bookdown.org/yihui/bookdown/) as well as searching
lorenzwalthert's avatar
lorenzwalthert committed
128
through stack overflow / Google for particular questions. In addition,
lorenzwalthert's avatar
lorenzwalthert committed
129
130
131
132
inspect the different files in this repo, in particular the ones in the
rmd directory to develop a deeper understanding of the template.

As of early 2018, this template is still in alpha testing phase, so you
lorenzwalthert's avatar
lorenzwalthert committed
133
may experience unexpected behavior. Please file an issue on the git
lorenzwalthert's avatar
lorenzwalthert committed
134
135
repository where you have obtained the source of this template in case
you are stuck for some time with a problem or if you found a solution to
lorenzwalthert's avatar
lorenzwalthert committed
136
137
138
139
a problem you believe others are likely to encounter in the future. Pull
requests on typos are also welcome. We want to make sure that students
working this template have a great experience writing their master
thesis.
lorenzwalthert's avatar
lorenzwalthert committed
140
141
142
143

Best,

Nicola Gnecco and Lorenz Walthert
lorenzwalthert's avatar
lorenzwalthert committed
144
145
146
147
148

1.  Below, we even used the bash command `tree` to show the directory
    structure of this repo. Since unicode is not suppored with pdflatex,
    we used R code to tell knitr to use the tree command with the option
    `charset unicode` for pdf output and without it for html output.