When a girl asked me 20 years ago "What a perfect date would be", I answered enthusiastically "ISO8601, of course".
I'm still single today, and I don't know why.
(Just kidding :)
30 karma · joined December 8, 2012
I'm still single today, and I don't know why.
(Just kidding :)
https://bookdown.org/yihui/rmarkdown-cookbook/latex-hardcore...
https://bookdown.org/yihui/rmarkdown-cookbook/html-hardcore....
Well, you might be too optimistic about people not commenting on R. Usually I tend to avoid reading HN, but I feel pretty much every single time when someone brings up anything related to R, some people will start mentioning how terrible R is, sooner or later :) Now people also start fighting around Tidyverse, although I have no idea why that's relevant to R Markdown...
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.
The blog post is not really long, and in the fourth paragraph, I wrote:
> [...] We used books and R primarily for examples in this book, but bookdown is not only for books or R. Most features introduced in this book also apply to other types of publications: journal papers, reports, dissertations, course handouts, study notes, and even novels. You do not have to use R, either. Other choices of computing languages include Python, C, C++, SQL, Bash, Stan, JavaScript, and so on, although R is best supported. You can also leave out computing, for example, to write a novel.
Perhaps one thing I didn't make clear enough is that (you are right that) R (optionally RStudio) should be downloaded to use bookdown locally, but your document or book does not have to be related to R or statistics at all. However, I do agree that people who don't use R probably won't care about downloading R in the first place to use bookdown, so even if bookdown is sort of "general-purpose", the actual major audience is likely to be those doing statistics and data analysis using R.
That said, Sections 5.5 and 6.2 of the bookdown book have shown how to use bookdown on Github and Travis CI: https://bookdown.org/yihui/bookdown/ That way, you don't have to install R locally. All you need to do is to commit changes to Github, and the book can be built automatically on Travis and published to Github pages. The author has to find someone to help him/her set up these services, though.
We take reproducibility very seriously. The fact that RStudio's Knit button uses a new R session, instead of the current R session, to compile R Markdown documents was a deliberate choice to make sure your output is produced from a clean R session. But if you are doing EDA, it may not be very pleasant to click this button over and over again every time you update your code (you can if you want).
If your course is focused on software engineering, everything you said makes perfect sense. Statisticians can learn the good principles in CS, but they are statisticians after all. There must be tradeoffs.
As someone who had been a student in statistics for more than 10 years, I confess I had never written a single test for my homework. Frankly I just didn't have the time or interest (too much homework, and becoming a professional software engineer was not the goal of the homework assignments). That said, when I put on my software engineer hat now at work, I'd definitely do what you advertise here and write tests carefully. If you want your students to enjoy the benefits of both R packages and R Markdown, I wrote some thoughts here a couple of years ago: http://yihui.name/rlp/
Don't get me wrong. I'll all for teaching students good practice of software engineering. I just want to speak from my own memories and experience as a student. Sometimes I feel teachers are like parents: they want kids to learn all possible right things, no matter if they are practically able to swallow all the good stuff (sometimes this has bad psychological consequences, like rebellious children). If I were an instructor in statistics, I'd only require students to submit an R Markdown document. Other things like tests can earn extra credits but not required.