
Bookdown – Authoring Books and Technical Documents with R Markdown - yomritoyj
https://blog.rstudio.org/2016/12/02/announcing-bookdown/
======
anacleto
If you use R on a daily basis this is a very nice feature.

------
IndianAstronaut
R with Rstudio is making some major progress in using R for presenting.
Rmarkdown, ReportRs for PowerPoint and now this.

------
hoodwink
I _love_ Bookdown, but only once I figured out how to incorporate it into my
writing workflow.

I'm writing a ~150 page monograph. As the document evolved, organizing the
prose and reordering the structure gradually became too cumbersome in plain
text Markdown files (whether I used R Studio or some other editor). So I
shifted my writing over to Scrivener---the best long-form writing tool I've
ever used, highly recommended.

I write RMarkdown in Scrivener and compile the document into plain text. I
manage my reference materials Zotero and export bibtex bibliography. Bookdown
then takes the two files, incorporates all my calculations, tables, plots, and
figures, and outputs a beautifully rendered document.

~~~
iamwil
Why was the prose and reordering too cumbersome? was it updating all the
references or something else?

~~~
hoodwink
It's just the process of organizing your ideas in a logical order. At the
start, I have a bunch of ideas and I do my best to organize them into an
outline. But as I begin writing and continue my research, I realize that some
of my ideas suck, or I have new, better ideas, or I see a better way to share
my ideas with the reader, so I need to constantly reorganize my document.

I don't know if this process is a sign that I'm an amateur writer or not, but
Scrivener makes document organization incredibly simple compared to writing in
a normal text editor. It also enables me to keep my notes sorted without
interfering with the prose.

By the way, updating all the references is very easy using Bookdown and a
bibtex bibliography.

------
nonbel
I still lose all formatting when copy-pasting code from the pdfs being
generated. Why does that need to be a problem? Eg from page 47:

    
    
      ---
      title: "An Impressive Book"
      author: "Li Lei and Han Meimei"
      output:
      bookdown::gitbook:
      lib_dir: assets
      split_by: section
      config:
      toolbar:
      position: static
      bookdown::pdf_book:
      keep_tex: yes
      bookdown::html_book:
      css: toc.css
      documentclass: book
      ---

[https://bookdown.org/yihui/bookdown/bookdown.pdf](https://bookdown.org/yihui/bookdown/bookdown.pdf)

~~~
yihui
Because PDF is for printing purposes. There could be many many problem if you
copy and paste from PDF (white spaces being eaten, ligatures, curly quotes,
en/em-dashes, ...; almost as bad as Word, except that PDF is beautiful). So
don't copy from PDF, but from HTML instead. HTML is much more faithful in
terms of preserving characters.

~~~
nonbel
So it is just an inherent limitation of pdfs? That's too bad, for some reason
I find the html format less intuitive.

------
applecrazy
Can somebody explain to me why they would download a programming language just
to write a technical paper? I get that it's a replacement for TeX, but with a
name like Bookdown, I expect it to be as simple as Markdown in terms of setup.

~~~
dandermotj
It's not a replacement for TeX. R originally had Sweave for weaving R and text
together. Then we got Rmarkdown, which introduced the use of markdown for
authoring documents via pandoc, but the output document only had simple
features like headers, sub headers, emphasis and so on.

Now Yuhui from Rstudio (who's been prolific in this area) has written bookdown
for authoring books with rmarkdown. It's not for authoring statistical papers
(as the other comments stated - that's rmarkdown's realm) it's for books like
Hadley Wickham's R4DS and Advanced R. Other examples can be found on the
bookdown website.

I'd also add that, regardless of inserting R code, bookdown is a class
authoring format and personally I would write a book or large document in
bookdown even if it was just pure prose.

~~~
Noseshine

      > It's not for authoring statistical papers (as the other comments stated
    

While you are technically right what will most likely happen is what we can
already see (on [https://bookdown.org/](https://bookdown.org/)) - exactly what
I described in my comment. _Of course_ one could write a novel with it. Any
publishing tool can be used to publish "just text". But who is going to end up
using this tool? Pretty much only people already using R, and that - apart
from people taking a course - is people doing statistics.

I looked at two randomly selected pages in two randomly selected books on the
homepage (I swear I didn't click on more than those two to select examples
that fit my narrative), both show it's being used just as I said.

\- [http://r4ds.had.co.nz/exploratory-data-
analysis.html](http://r4ds.had.co.nz/exploratory-data-analysis.html)

\- [https://bookdown.org/robertkck/ecf_draft/low-carbon-is-
promi...](https://bookdown.org/robertkck/ecf_draft/low-carbon-is-
promising.html#low-carbon-technology-in-innovation-and-export) (this one has
interactive graphics)

My reply was aimed at someone who doesn't seem to know any of the background
story.

I agree with you that it's a nice tool for a lot of purposes.

------
joncalhoun
Has anyone used both Bookdown and Softcover [1] to compare the two?

Softcover is something similar written in ruby that uses a combination of
markdown with latex where necessary to generate HTML, PDF, ePub, and mobi book
formats. It is what Michael Hartl uses (and created iirc) to build Rails
Tutorial.

While it seems tightly linked with the Softcover publishing service, you can
use the files it generates pretty much anywhere in my experience.

[1]
[https://github.com/softcover/softcover](https://github.com/softcover/softcover)

~~~
yihui
A few differences I spotted as I quickly read the Softcover book (I'm the main
author of bookdown, so I could be biased):

Bookdown is built on top of R Markdown, which means it has the genes of
literate programming (knitr) and Pandoc. Literate programming is an important
bridge to reproducible research (source code and prose in the same document),
which we strongly believe in. We also value Pandoc's efforts in standardizing
Markdown, although John Gruber didn't seem to care [1].

Softcover seems to be focused on the typesetting syntax, cherry-picking from
different flavors of Markdown plus LaTeX when Markdown cannot get you there.

I think the design of these tools is heavily influenced by the background of
their authors. I have been a student in the statistics major for several
years, and published a few academic papers, a PhD thesis, and a book before,
so I know some of the pain of publishing these things. The overall feeling you
get from bookdown may be "hmm, this is for people in the academia" (who else
cares about equations or theorems after all). By comparison, the feeling I get
from Softcover is "this is for software manuals" (who else would care about
code listings). Neither feeling is accurate: bookdown is not only for academia
and softcover is certainly not only for software manuals.

There are certainly many differences in the Markdown syntax, but I don't think
it is worthwhile listing them here. One subtle thing is that on bookdown book
pages, you may see an edit button that takes you to Github to edit the R
Markdown source, then send a pull request. This little feature is one of my
personal favorite features.

Another major difference is that Softcover provides the service of marketing
and selling as well, and bookdown is only a tool for authoring books at the
moment (you have to talk to publishers by yourself). Both self-publishing and
publishing with an established publisher have their pros and cons, e.g. the
former is quick and the latter is slow. We leave the decision to the authors.
Several platforms for self-publishing exist, and authors can send the PDF/EPUB
there if they want.

[1]
[https://twitter.com/markdown/status/507341395137658880](https://twitter.com/markdown/status/507341395137658880)

------
iamwil
Anyone know what markup language was used to express the math equations? Was
that Tex or something else?

~~~
yihui
Yes, the syntax is LaTeX (thanks to MathJax). See Chapter 2 of the bookdown
book:
[https://bookdown.org/yihui/bookdown/](https://bookdown.org/yihui/bookdown/)

------
rcarmo
I've been toying with [http://weasyprint.org](http://weasyprint.org) and
Python markdown toward similar (but as yet unrealized) effects, and quite like
the idea.

It's not too hard to, say, write a Python Markdown extension to do the same
using pandas, seaborn and the usual data science tools from the Python
universe, but I salute the R folk for getting this done in what appears to be
a quite consistent fashion.

