mlr-org / Mlr3book
Programming Languages
Projects that are alternatives of or similar to Mlr3book
mlr3book
Package to build the mlr3 bookdown book.
Rendered Versions
Building the book
To install all necessary dependencies for the book, install this R package using remotes:
remotes::install_github("mlr-org/mlr3book", dependencies = TRUE)
To build the book, run one of the following commands:
# HTML
withr::with_dir("bookdown", bookdown::render_book("index.Rmd",
output_format = "bookdown::gitbook"))
# PDF
withr::with_dir("bookdown", bookdown::render_book("index.Rmd",
output_format = "bookdown::pdf_book"))
Serve the book
Alternatively, you "serve" the book via a local server:
bookdown::serve_book("bookdown")
The command above starts a service which automatically (re-)compiles the bookdown sources in the background whenever a file is modified. If your browser does not open automatically, go to http://127.0.0.1:4321/.
Makefile approach
Alternatively, you can use the provided Makefile
(c.f. see make help
).
This way, you can
- install dependencies
- build the HTML book ->
make html
- build the PDF book (
bookdown:pdf_book
) ->make pdf
File system structure
The root directory is a regular R package. The book itself is in the subdirectory "bookdown".
Style Guide
Lists
For lists please use *
and not -
.
Chunk Names
Chunks are named automatically as [chapter-name]-#
by calling name_chunks_mlr3book()
:
mlr3book::name_chunks_mlr3book()
or alternatively executing make names
from the terminal.
Figures
You have to options to include a figure:
- Vector graphic
- In the
Rmd
:knitr::include_graphics("images/some_figure.svg")
- Add
bookdown/images/some_figure.svg
andbookdown/images/some_figure.pdf
to the repository.
- Pixel graphic
- In the
Rmd
:knitr::include_graphics("images/some_figure.png")
- Add only
bookdown/images/some_figure.png
to the repository.
- Do not use markdown syntax
[](<figure>)
to include figures. - Do not include
pdf
in theRmd
:knitr::include_graphics("images/some_figure.pdf")
.
Adding a new figure
To add a new figure into the repository consider the following rules:
- Add the file in the
bookdown/images
folder without any subdirectory. - Store the original figure as a
svg
file if possible, i.e. if it is a vector graphic. This allows us to re-use or modify images in the future. -
png
files should have reasonable resolution, i.e. the width of a pixel graphic should be between400px
and2000px
. If a higher resolution is needed to obtain a readable plot you are probably doing something wrong, e.g. use a pixel graphic where you should use a vector graphic. - Please look at the file size.
- If your
pdf
orsvg
file is larger than1MB
it probably contains unnecessary hidden content or unvectorized parts. - If your
png
file is larger than1MB
the resolution is probably too big.
- If your
Further aspects
- How do I convert
svg
topdf
?- Use Inkscape or any other tool which does not convert to raster images.
- How do I convert
pdf
tosvg
?- Use Inkscape which allows you to also remove unwanted parts of the
pdf
.
- Use Inkscape which allows you to also remove unwanted parts of the
- Do not use screenshots!
-
Google Slides allows
svg
export. -
PDF can be converted to
svg
and you can even cut parts. -
HTML can be converted to
svg
.
-
Google Slides allows
- The difference between vector (
svg
) and pixel (png
) graphics should be known.- Attention:
svg
andpdf
also support to include pixel graphics. There is no guarantee that asvg
orpdf
is a pure vector graphic. If you paste a pixel graphic (e.g. a screenshot) into Inkscape and save it assvg
it does not magically become a vector graphic.
- Attention:
Spacing
- Always start a new sentence on a new line, this keeps the diff readable.
- Put an empty line before and after code blocks.