Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

【全书】格式约定 #13

Closed
XiangyunHuang opened this issue Aug 16, 2019 · 26 comments
Closed

【全书】格式约定 #13

XiangyunHuang opened this issue Aug 16, 2019 · 26 comments
Labels
第一版 第二版

Comments

@XiangyunHuang
Copy link
Owner

XiangyunHuang commented Aug 16, 2019 •
edited
Loading

@yihui @pzhaonet 写作约定见 https://bookdown.org/yihui/rmarkdown/software-info.html
@yihui yihui changed the title 写作风格 格式约定 Aug 16, 2019
@XiangyunHuang
Copy link
Owner Author

XiangyunHuang commented Aug 17, 2019 •
edited
Loading

大家共同讨论决定，我先写个开头

  1. R 包如 ggplot2 应该要用星号加粗表示为 ggplot2，而当表述为 ggplot2 系统时不需要加粗
  2. 文字段落中含有函数名称如 barplot 或 barplot(...) 应该放在一对反引号里，视作代码
  3. 文字中描述函数的参数时，如 barplot 函数的参数 beside 取值为 TRUE 或 FALSE ，那么参数名和参数值也都用一对反引号表示为 barplot 函数的参数 beside 取值为 TRUE 或 FALSE 。理由是这些都与代码密切相关，统一为代码字体应该是合理的，复制粘贴会比较方便，在网页中显示也比较醒目。添加反引号的操作也比较容易，不用按住 Shift 键

@pzhaonet
Copy link
Collaborator

同意。

关于函数名，由于我是从 .tex 转成的 .md，保留了斜体格式，目前已经完成的章节均如此，我暂时不想返工，想到最后用正则处理一下，改成代码格式。

关于参数，原稿用的是无衬线字体，改为代码格式是妥当的。不过，我已完成的章节，被我不慎改成普通文本了。后面的章节我会改成代码格式，但已经完成的，正则替换难度大，可能需要肉眼，我暂时不想返工，不如等最后统稿再修改吧，幸好不太多。

@XiangyunHuang
Copy link
Owner Author

XiangyunHuang commented Aug 18, 2019 •
edited
Loading

  1. 文中的数据集，及其各个变量名称，也把它们看作代码，因为加载之后，也是可以直接当作代码在控制台运行的

  2. 脚注不要以数字编号，也不要离所注内容太远，应以合适的命名，并位于所注节内，为的是好对应，就近查看和修改，补充例子见 ca8cee9

  3. 全书代码环境中参数 help.search('analysis of variance') 单引号全部改为双引号，要统一

@XiangyunHuang XiangyunHuang added the documentation Improvements or additions to documentation label Aug 18, 2019
@XiangyunHuang XiangyunHuang changed the title 格式约定 【全书】格式约定 Aug 19, 2019
@XiangyunHuang XiangyunHuang added good first issue Good for newcomers 第二版 and removed documentation Improvements or additions to documentation good first issue Good for newcomers labels Aug 20, 2019
@JackieMium
Copy link
Contributor

我知道大家都是对排版、格式有一定要求甚至是小强迫症的人，所以我提出这个问题应该不会有人打我吧：

image

这是我看 序言 的一张截图。1 的位置单词两侧都空格隔开 ✔，3、5 两处又没有，而 2、4 和 6 个人觉得也应该有空格隔开比较好这里也没有。

这些大概可以用脚本一次性来做，人工改然后一个个 PR 那估计 commit history 会乱掉，所以我就只来提一下不 fork & PR 了。

@XiangyunHuang
Copy link
Owner Author

@JackieMium 如果你有批处理的脚本附上的话，欢迎 PR

@yihui 盘古库如何引入 bookdown 能否介绍一些思路？

@JackieMium
Copy link
Contributor

抱歉，我自己倒不会写脚本，但是之前使用过 robot527/add-spaces 批量处理过一些 md 文件，似乎没有什么大问题。

@yihui
Copy link
Collaborator

yihui commented Aug 30, 2019

这个建议还是正则表达式批处理一下源文件吧，不用盘古了，因为反正 PDF 输出也得加空格。

@XiangyunHuang
Copy link
Owner Author

中英文、数字之间留间距 俗称盘古之白

一些注意到的现象暂记于此

  1. 代码块里的中英文不要处理
  2. 引用环境 \@ref(sec:dynamic-graphics) 不要改为 \@ref (sec:dynamic-graphics)

@pzhaonet
Copy link
Collaborator

正则处理起来好像难度挺大的。在尚无靠谱方案的情况下，可能人工处理更放心吧，毕竟就算是正则处理完了仍然得肉眼检查。

如果有完美方案，非常期待。

@XiangyunHuang
Copy link
Owner Author

我也是感觉难度很大，心里已经拒绝了好多次，应该把锅甩给 @yihui ，毕竟谢大好几个 R 包里的正则都占有举足轻重的地位

@JackieMium
Copy link
Contributor

我直接 clone 下来然后 RStudio preview book 装了一堆包还是失败了，打算用一下 docker 镜像，已经 pull 下来了但是还不知道怎么用，正在临时学习一下 docker 怎么用......

我觉得可以直接用上面我发的那个脚本先跑一下然后在人工检查一下，这样其实工作量应该小很多？或者是一个人 clone 下来新建一个分支，用脚本处理好直接 push，然后分工一下几个人一人检查一章并 push，最后确认无误所有分支再合并到 master 就行了，这样应该分分钟就做完了？

我去看 docker 用法去了 : (

@XiangyunHuang
Copy link
Owner Author

编译书籍只有两步

  1. clone 下本仓库后，从 Git Bash 切换目录到书籍项目
  2. 运行 docker-compose run book bash -c "sh ./_build.sh"

而且我在 Travis 上把这细节也曝光

https://github.com/XiangyunHuang/MSG-Book/blob/feadccaae1aee468d8761d6f22d61576a075fe19/.travis.yml#L30-L38

@XiangyunHuang
Copy link
Owner Author

装 Git 和 Docker 也就 Windows 平台麻烦， Linux/MacOS 上都是一行命令的事

@JackieMium
Copy link
Contributor

JackieMium commented Aug 30, 2019 via email

@XiangyunHuang
Copy link
Owner Author

  1. 克隆本仓库，进入本项目根目录

    git clone https://github.com/XiangyunHuang/MSG-Book.git && cd MSG-Book

  2. 接着执行如下一行命令

    docker-compose run book bash -c "sh ./_build.sh"

@JackieMium
Copy link
Contributor

image

算了，个人宣布放弃 docker。有这个时间学这个人肉插空格可能都做好几个文件了。

@XiangyunHuang
Copy link
Owner Author

XiangyunHuang commented Aug 30, 2019 •
edited
Loading

你这应该不是在容器里编译吧？

当初以 Docker 镜像的方式打包所有书籍项目依赖是我做的，出于以下几个点的考虑

  1. 要用户挨个把 R 包都装上，这是一项大工程，不仅量多，而且有些 R 包依赖高度复杂，还要面对不同的用户环境（Windows/Linux/MacOS），真心不想花时间介绍这个东西 【全书】不同平台的适应性 #35
  2. 借助 Travis 测试用户提交的 PR，还是那个问题 --- 在 Travis 上装那么多 R 包光是下载安装一堆系统软件依赖就要好些时间，启用缓存后，每次编译还是要下载安装那么多软件依赖， Travis 报错了有时候很难查找原因，我本地没有 Travis 的系统环境，自制容器环境完全可控
  3. 省下这么多时间和空间，我就可以在 Travis 上编译书籍时，执行所有代码，同时生成 HTML 和 PDF 格式文档，显示所有执行过程，好 debug
  4. Travis 指示器亮着绿灯意味着代码都没有问题，从维护性上来说也方便，好维护
  5. 那些不满足于网页书籍，想动手本地编译出离线版本，就要做好准备，要么本地安装所有软件和R包，要么再安装一款 docker 软件。我原不打算介绍如何使用 docker 以及如何复现，这属于高级读者的内容，如果是高级读者他们自然知道去看我项目里的 docker/ 文件夹和 .travis.yml 文件

@pzhaonet
Copy link
Collaborator

pzhaonet commented Aug 30, 2019 •
edited
Loading

确实是。我用 travis 直接编译，一直通不过，试到第 13 次，遇到tcltk 和 sm 的问题，失去了耐心，放弃了。docker 暂时没时间学，因为是瘟都死。

@XiangyunHuang
Copy link
Owner Author

我主机也是瘟都死，所以才学的 docker 之前是先装 VBox， 再在里面装 Ubuntu/CentOS 之类的感觉太麻烦，就转到 docker 。我上面给出的常用 docker 命令基本就够了，对大多数人来说，不需要往下再学。

@JackieMium JackieMium mentioned this issue Aug 30, 2019
Merged
@XiangyunHuang
Copy link
Owner Author

XiangyunHuang commented Aug 31, 2019 •
edited
Loading

  1. 脚注不要以数字编号，也不要离所注内容太远，应以合适的命名，并位于所注节内，为的是好对应，就近查看和修改，补充例子见 ca8cee9

  2. 全书代码环境中参数 help.search('analysis of variance') 单引号全部改为双引号，要统一

@JackieMium
Copy link
Contributor

一边看的过程中发现一些小的 typo 或者是语句不通/错误的时候怎么改呢？fork 之后 PR 回来效率还是低，而且我是有空就翻看一些有的地方只能发现错误不知道改怎么改。比如我看第一章 「1.5 小结与开始」 最后一自然段：

总的说来，要把图形提到“统计分析”的高度，就一定要搞清楚统计图形的来龙去脉，包括原始数据的来源和类型、统计量的计算、图形的构造与组合机制等，这与统计模型实际上没数据的分布状况、离群点、线性 / 非线性关系等表面观察，而更重要也是最本质的莫过于洞察到种种规律或异常现象背后的深刻原因，至此，我们才达到了分析的目的。

第一处加粗我不知道这个“没”是错字还是什么，所以我 fork 了也不知道怎么改。第二处“线性 / 非线性关系”似乎是在处理加空格的时候多加了空格。/ 表示和/或的时候两边不加空格比较妥当。

@XiangyunHuang
Copy link
Owner Author

谢谢指出来，这是我们搬迁的时候出错

@pzhaonet
Copy link
Collaborator

pzhaonet commented Jul 11, 2020 •
edited
Loading

我主机也是瘟都死，所以才学的 docker 之前是先装 VBox， 再在里面装 Ubuntu/CentOS 之类的感觉太麻烦，就转到 docker 。我上面给出的常用 docker 命令基本就够了，对大多数人来说，不需要往下再学。

花了整整一天来折腾书稿的编译，以失败告终。简单来说就是我的 Windows 10 版本不支持 Docker 的安装，而且看网上的教程貌似即使装上之后仍然得折腾，而我这里的网络条件是连访问 github 都不稳定......

打个蚊子没必要花精力架高射炮，我决定这次放弃 Docker，从零开始配置一个不依赖 docker 就可以编译本书的 bookdown 最简环境。

@XiangyunHuang
Copy link
Owner Author

大家没必要把精力花在 Docker 上，从出版社的角度想也不希望我们早早地提供这方面的便捷性，我们也没必要编译成 PDF 因为我发现出版社极有可能不要我们去编译 PDF 而是根据我们的网页版自己编辑

@pzhaonet pzhaonet mentioned this issue Jul 13, 2020
Closed
68 tasks
@pzhaonet
Copy link
Collaborator

大家没必要把精力花在 Docker 上，从出版社的角度想也不希望我们早早地提供这方面的便捷性，我们也没必要编译成 PDF 因为我发现出版社极有可能不要我们去编译 PDF 而是根据我们的网页版自己编辑

根据网页版去编辑的话是出力不讨好。出版社有专管录排的工作人员，但是我严重怀疑在有现成latex书稿的情况下还脱离 latex 去排版的可能性。我上次出书的这个过程极其痛苦，录排非要用 Adobe Illustrator，结果是错误百出，反复沟通，按了葫芦起了瓢，白白浪费进去半年，最后还是拿我做好的 pdf 去印刷了。

@XiangyunHuang
Copy link
Owner Author

@pzhaonet 看出版社的反馈吧，这本书一开始就流淌着 LaTeX 的血液的，所以我说要把她们的模版拿到

@pzhaonet pzhaonet mentioned this issue Aug 12, 2020
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
第一版 第二版
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@yihui @pzhaonet @XiangyunHuang @JackieMium