A Few Tips for Writing an R Book | /en/2013/06/tips-for-writing-an-r-book/

yihui 2022-12-16 23:06:44

A Few Tips for Writing an R Book

https://yihui.org/en/2013/06/tips-for-writing-an-r-book/

10 Comments

giscus-bot 2022-12-16 23:06:45

Guest *baptiste auguie* @ 2013-06-04 13:43:35 originally posted:

Well done, congrats!

Two comments:

re punctuation inside quotation marks: I believe this is a matter of style and convention. I once read in a manual of style (or in "elements of typographic style", I forget) that either option is acceptable. Whatever the editor thinks is the One True Way, basically.
visual tests: there's a vtest package at least for ggplot2, see
https://github.com/wch/ggplot2/wiki/Visual-test-system

http://stdout.org/~winston/vtest-demo/diff/minor-breaks.html

PS: you didn't write in markdown!? I'm shocked :)

yihui 2022-12-16 23:06:54

No, I ended up with LyX/LaTeX. I know everybody is surprised. If I were
to write an e-book, I would probably use Markdown; for a hard copy, I
still need careful typesetting.

Originally posted on 2013-06-04 19:15:17

giscus-bot 2022-12-16 23:06:54

Guest *Carl Boettiger* @ 2013-06-06 01:40:23 originally posted:

Adjusting pandoc's LaTeX templates one can get pretty far leaving the source in markdown and pulling content chunks into the tex file (as I think you know better than me!) Of course you still have to fiddle with a lot of LaTeX for formatting, but you can separate that typesetting / styling from the coding. (I see this approach as analogous to Jekyll, latex ～ _layouts, .cls ～ .css). I suppose that approach wasn't quite flexible enough?

yihui 2022-12-16 23:06:55

That approach is indeed very flexible. Technically I could go that way. At the moment, there is nothing difficult in the back-end. I just need a front-end (visual aid like a GUI) for markdown to manage a few things: figures (I hope I can see them), cross-references, and citations. Actually there is one more thing that is not possible for Pandoc's markdown: the short captions for figures/tables, which are important for the lists of figures/tables.

Anyway, LyX has done a decent job of hiding gory details of LaTeX without sacrificing the power of LaTeX, so I just went with it.

Originally posted on 2013-06-06 22:18:08

giscus-bot 2022-12-16 23:06:56

Guest *ping* @ 2013-06-10 18:52:17 originally posted:

I think lyx is not the only thing between markdown and latex, have a look at asciidoc if you want to be surprised...

yihui 2022-12-16 23:06:57

I have already been surprised a while ago, and that is why I decided to support AsciiDoc in knitr :)

But I mean I do not want to look at the source code while I'm writing something long such as a book. AsciiDoc is good, and what I really need is "Microsoft Word for AsciiDoc". Put it another way, a sophisticated GUI for a simple back-end (Markdown/AsciiDoc/reSt/...). To be clear, I hate Word, but I do not think Word is terrible in all aspects.

Originally posted on 2013-06-10 19:57:35

giscus-bot 2022-12-16 23:06:59

Guest *M. Edward (Ed) Borasky* @ 2013-08-04 23:03:42 originally posted:

I was able with some simple scripting, Sigil and Calibre, to export a LyX document to "strict xhtml" and get a serviceable EPUB. But it was ratty looking.

giscus-bot 2022-12-16 23:06:46

访客 *liyun* @ 2013-06-06 08:36:58 写道：

求个preface...

@cloudly

giscus-bot 2022-12-16 23:06:46

Guest *Yinbo  Chen* @ 2013-06-08 05:56:30 originally posted:

already pre-ordered on amazon...it will be a fantastic book.

giscus-bot 2022-12-16 23:06:47

Guest *Gene* @ 2013-06-10 19:54:40 originally posted:

Your tips on English are good tips that trouble native English speakers as well. Some of the tips are also more matters of style, not hard and fast rules. Some people / institutions have different rules on some of those.

yihui 2022-12-16 23:06:58

Thanks! Glad to know that :)

Originally posted on 2013-06-10 19:58:42

giscus-bot 2022-12-16 23:06:48

Guest *M. Edward (Ed) Borasky* @ 2013-08-04 23:00:32 originally posted:

I can understand why you'd prefer LyX to raw LaTeX, but would you recommend an author writing a similar book starting today stay with LyX or use a Markdown / Pandoc toolchain?

yihui 2022-12-16 23:06:59

For today, still LyX. But I think I will recommend Markdown when the publishers support publishing books as web pages (it is difficult to get Markdown printed nicely). This is one thing I have been talking to them for a long time, but have not reached a conclusion yet.

Originally posted on 2013-08-05 05:19:00

giscus-bot 2022-12-16 23:06:49

Guest *Jared* @ 2013-08-05 04:29:10 originally posted:

Totally agree with the first two points; couldn't have written my book without knitr or version control.

My editors wanted me to use an oxford comma too (point 5) but I just couldn't do it.

Tried using Cairo_png mostly, but some images didn't looked good so I just used png.

Absolutely make as many images as possible and maybe have three monitors.

yihui 2022-12-16 23:07:00

Since a certain version of R (I do not remember which), png() uses cairo by default, so it does not make much different to use Cairo_png() or png(). I was talking about cairo_pdf() instead of Cairo_png() for font embedding purposes.

Originally posted on 2013-08-05 05:21:37

giscus-bot 2022-12-16 23:07:01

Guest *Jared* @ 2013-08-06 05:32:30 originally posted:

Your cairo mention made me think of my uses of cairo_png. Changing the dev to png, from cairo_png, remarkably improved the resolution for complicated plots like coefplots. Don't know why considering you say they're now the same.

Is cairo_pdf that much better than png?

yihui 2022-12-16 23:07:02

It is a matter of choice, depending on whether you want vector graphics or raster images. For LaTeX/PDF output, I believe it is certainly better to use PDF devices such as pdf or cairo_pdf.

Originally posted on 2013-08-06 08:12:59

giscus-bot 2022-12-16 23:06:50

Guest *QAChip* @ 2013-09-07 02:33:23 originally posted:

Kudoz PhD. Yihui,

As soon as I knew there was a book on knitr, I bought a copy for myself. I'm glad to say that (maybe) I'm the owner of the only/first hard copy in Mexico.

You can go to my Github slash my nickname and see a piece of my MSc thesis (sorry, it is written in spanish). It is written in LaTeX+knitr.

Great job, I hope you keep on like this.

giscus-bot 2022-12-16 23:07:03

Guest *Marco* @ 2013-10-21 16:52:19 originally posted:

Hi,
Well, I also bought a copy for myself and I live in Mexico too, Perhaps you are the second one.
Best whishes

giscus-bot 2022-12-16 23:06:51

Guest *isomorphisms* @ 2014-02-13 22:41:02 originally posted:

Quote-marks work as you want them to in British English.

yihui 2022-12-16 23:07:04

Thanks! Interesting to know this.

Originally posted on 2014-02-14 03:32:38

giscus-bot 2022-12-16 23:06:52

Guest *isomorphisms* @ 2014-02-13 22:41:26 originally posted:

Oh, and congratulations on publishing your first book!

giscus-bot 2022-12-16 23:06:53

Guest *do my essay* @ 2015-05-27 03:10:26 originally posted:

Writing this kind of book may not be the important for someone who wanted to improve their ability when it comes into writing. At least they can gain some few tips that might be added on their ability to produce a better output.