把书里所有的作图代码全部写进包里
pzhaonet opened this issue · comments
把书里所有代码做出来的图的代码，加上详细注释，全部写进 MSG 包里，并且在书里相应的位置说明，例如在图的 Caption 里。
这样做的好处有三：
- 保持全书的一致性。目前有些地方是全代码，有些地方用 demo()，风格不统一。
- 方便读者重现图形。一句代码出图，从读者角度会很爽。也方便那些 R 初学者或者非 R 用户，说不定因为这个就爱上 R 了。
- 方便更新升级。万一将来因为各种变化导致书里的大段代码失效，至少读者可以运行 demo() 来画图和获取新代码。这样，书的生命力会更久。这个意思可以在前言里说明。
甚至可以在 demo 里写个 hello.R，作为开场白。当然也可以写进 vignette 里。
不过，我没有写 demo 的经验，不知道这样会不会在 CRAN 审查的时候出现一些麻烦。比如在包的函数里是不许有中文字符的，那么 demo 里呢？demo 里加载的包，是否需要在 DESCRIPTION 里声明？增加很多demo的话，会不会给 MSG 包的后期维护带来太多麻烦？
这个好办，绕过 demo() 即可，这样就不必担心 CRAN 警察了。比如 shiny 就有自己的 shiny::runExample()。这样你把那些示例代码放到 inst 目录下任何一个子目录下即可，比如 inst/examples，下面放一个个 .R 脚本。然后 MSG 包里提供一个 book_example() 函数，跑 source() 即可。
如果是大段代码的例子，又不需要读者读懂代码，可以这样办。对于小段的例子，或者是源代码比较重要的例子，我觉得把源代码塞在书里也未尝不可。
嗯，也就是说，demo/ 里的脚本会被 CRAN 审查，而 inst/ 里的不会？
要是 demo/ 里没那么多鸡毛蒜皮条条框框限制的话，我觉得还是尽量用 demo() 函数调用。这样读者画图前就不必加载 MSG 包了，书稿现在涉及 demo() 的地方也不用改成 book_example()。
最后一个，是的，现有书稿里的源代码暂时保留。读纸书的时候手边未必有电脑来运行 demo() 看源码，这时纸书里的代码还是很有用的。现在就是担心篇幅——出于印刷成本和市场的考虑——已经400页了，这还不包括 shiny 节、plotly 节以及我准备在图库举例时添加对 ggplot 里各种函数的介绍。如果不得不缩减篇幅，大段的代码是个下狠手的地方。别的地方实在舍不得。
我不知道 R CMD check 是否检查 demo/ 下的代码，感觉应该是不检查，我唯一不确定的就是中文字符是否会有问题，不过这个应该容易验证，我一会儿试一下。
不能用中文字符，否则会有警告：
* checking package subdirectories ... WARNING
Demos with non-ASCII characters: ChinaPop.R
Portable packages must use only ASCII characters in their demos.
Use \uxxxx escapes for other characters.
得用转义符，像这里面的中文字符一样：https://github.com/yihui/MSG/blob/master/demo/ChinaPop.R
转义符太不人道了。偶尔几个字符还行，而我是想逐行加中文注释给初学者理解代码用的。
我想起来了：以前我的做法是把中文长句写到 inst/ 某个文件里，用到的时候就读进来。比如 sinx 包涉及中文语录的地方就是这么干的。而写 pinyin 包的时候，汉字转拼音函数的 example 字段不允许用中文——一个用来处理中文的包，你不让我拿中文举例子，那么例子有啥意义？从此对 CRAN 累觉不爱。
那我就写到 inst/ 里，弄个函数调用吧。book_example() 读者敲起来太长，不如就叫 msg()：
msg <- function(fig = "AgriComp"){
source(system.file("examples", paste0(fig, ".R"), package = "MSG"))
}