Bookdown – Authoring Books and Technical Documents with R Markdown • Hacker News Board

Re: Bookdown – Authoring Books and Technical Documents with R Markdown

#21

Post by yihui » Sat, Dec 03, 2016, 8:13 PM UTC

nonbel wrote: post #18

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/bookdow…

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.

Re: Bookdown – Authoring Books and Technical Documents with R Markdown

#22

Post by yihui » Sat, Dec 03, 2016, 9:08 PM UTC

joncalhoun wrote: post #19

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…

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

Re: Bookdown – Authoring Books and Technical Documents with R Markdown

#23

Post by nonbel » Sun, Dec 04, 2016, 1:46 AM UTC

yihui wrote: post #21

nonbel wrote: post #18

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/bookdow…

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.

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

Re: Bookdown – Authoring Books and Technical Documents with R Markdown

#24

Post by ivansavz » Sun, Dec 04, 2016, 6:18 AM UTC

joncalhoun wrote: post #19

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…

The main idea in softcover is to use (a restricted subset of) LaTeX as the "main" representation, which then gets converted to html + MathJaX using tralics (a latex-to-xml converter) and lots of custom pre-processing, and post-processing steps. The source code is quite readable. The end result is the following pipeline:

     .tex --> .html+MathJax --> .epub --> .mobi

The "Softcover-flavored Markdown" is just an optional convenience to enable people who don't know LaTeX to use the system as follows:

     .md --> .tex --> .html+MathJax --> .epub --> .mobi

The way I see the .md to .tex conversion is not that exciting, but the fact we finally have a civilized way to produce .epub/.mobi from .tex files is an amazing achievement. If you're working on books, I highly recommend checking out the softcover software stack.