Guidelines for Contributing

除去 FAQ 中提到的两种轻量级贡献方法外,你还可以采用 git 这种分布式协作工具一起改进这个文档。

如果你不确定自己是否会贡献较多的内容,那么在 GitHub 上 fork 后给我发 Pull Reqeust 就好了。如果你想成为 Collaborators 贡献大量内容, 那么请大胆给我发邮件(yuanbin2014(at)gmail.com),热烈欢迎~

总结一下 git 的工作流程就是:

  1. 更新上游 - git pull origin master
  2. commit 本地更改 - git commit -a -m 'xxx'
  3. 推送到上游 - git push origin master

有些时候在 commit 之前可能会忘记 pull, 那么此时 pull 将会产生一个 merge commit, 这显然是不太优雅的,建议使用git rebase -i 解决。

git 的简明教程可参考 b哥的 Git Manual, 小清新极简教程可参考 git - the simple guide - no deep shit!, rebase 的使用可参考 1, 2, 3

既然涉及到文档合作,那么最好是能有个像样的文档规范之类的东西方便大家更好的合(jiao)作(ji),目前想到的有如下几点。

更新/翻译特定语言

Gitbook 支持多语言书写,具体通过根目录下的 LANGs.md 目录指定,目前根目录下有en, zh-hans, zh-tw 三个子文件夹分别用于三种语言的书写,每个子文件夹相当于一个单独的 Gitbook, 与其他语言的文档是独立的,所以更新时只需在各自语言的目录下工作就好了。各语言的 SUMMARY.md 文件内容保持一致,且均使用英文。

目录生成

Gitbook 中使用SUMMARY.md这个文件控制生成目录,添加新内容时最好使用 Gitbook 家自带的编辑器添加,这样省事一点点。

文档格式及编辑工具 - GFM && kramdown Markdown

使用markdown编写,只使用 Gitbook 支持的 markdown 语法。Gitbook 底层的 markdown renderer 为改动的 kramdown,并增加了GFM支持, 支持的扩展 markdown 语法算是非常多了,具体特性详见 GitbookIO/kramed

推荐的 markdown 编辑器为 Gitbook 自家的 editor, 目前新版的 bug 太多,而且是自动 commit 的,不便于版本控制,希望他们后续能改进。所以目前推荐老版,老版的见 editor-lagecy, 支持 Windows/Linux/MAC 三大平台,业界良心!但是实测在Arch Linux/OSX 下可能会出现占用内存/CPU过高的情况… 编辑界面如下图所示,最左边为章节预览,中间为 markdown 编辑框,右边为实时渲染页面,可选择使用全屏模式。

Gitbook Editor

使用其他如 Mou/Vim/Emacs/Sublime Text也不错,但是在新增Chapter/Section时就比较闹心了,嗯,你也可以新建 Section 后再使用其他编辑器编辑。

对 Gitbook 不熟的建议看看 Gitbook Documentation,有助于了解 http://algorithm.yuanbin.me 网页上的文字及各章节等是如何编辑及渲染的。

章节名及编号

章节等文件名全部采用英文,子章节最多到三级,章节编号无需操心,这种琐事交给 Gitbook 去做就好,如果一定要手动调整,修改SUMMARY.md文件,注意其中的缩进关系,Gitbook就指望这个自动给章节编号了。

举个例子,我现在想新增「动态规划」及其子章节。首先在 Gitbook 顶部菜单栏「Book」中找到「Add Chapter」,填入「Dynamic Programming」。好了,在Gitbook左侧章节栏中就能看到新生成的「10. Dynamic Programming」了,左键击之,Gitbook 就会生成「dynamic_programming」目录及本章的说明文件「dynamic_programming/README.md」。如果想在「10. Dynamic Programming」下新增子章节,右键击之,「Add Section」即可,同上,子章节文件名仍然使用英文名,网页显示的标题可以通过 rename 更改再加入中文。

嗯,以上步骤均可直接新建文件夹及操作SUMMARY.md文件完成。

正文书写风格

  1. 中英文混排贯穿全文,优雅美观起见,尽可能在英文单词前后加空格,这个使用能在输入法中英文间加入空格功能就好了。
  2. 代码的函数名或短代码建议使用 `code`
  3. 使用空行进行分段,嗯,markdown通用

Part II为leetcode/lintcode题解,这部分的风格相对容易统一,感觉还不错的风格 - Distinct Subsequences

大致遵循如下风格:

  1. 给出题目链接及原文,引用的原文部分简单起见我对题目使用了blockquote ,具体可参考我的那些markdown文本。
  2. 给出自己的题解,尽可能清晰易懂。
  3. 给出能AC的code, 如遇TLE或者错误的看情况给出错误的实现。使用blockquote, 给出语言类别以便高亮。具体可参看原markdown文件。
  4. 题解中的核心部分对应的代码,代码中不能明显看出来的逻辑和一些编程上常用的技巧。
  5. 代码顺序:Python => C++ => Java 因为 Python 的代码一般最为简洁…
  6. 如参考了其他资源,尽可能给出有用的参考链接,附简单的说明。

通过github合作时,添加/修改内容时给出能看懂的commit就好了。暂时就想到这么多,其实没那么多讲究啦,感觉看着清楚就好,其他想到的再补充。:-)

数学公式

其实代码里是用不着写数学公式的,但是偶尔分析算法可能会用着,用过 LaTeX 的都知道她生成的数学公式有多优雅,以至于不用她来写数学公式都有点不舒服…

这个文档里对于较复杂的数学公式建议使用 LaTeX, 因为托管在gitbook上,所以就用了轻量级的katex插件,没有用重量级的 MathJax。行内和行间公式都是 两个$, 区别在于行间公式写到下一行行首,而行内公式不能写在行首(废话…)。katex非常脆弱,对一些高级的 LaTeX 语法不支持,否则无法编译输出到网站和pdf,尽量用简单的 LaTeX 语法或者不用。

附件及图片引用

图片统一存放在images目录下,其他附件存放在docs目录下。引用图片链接一般可以通过![Caption](../../shared-files/images/xxx.png)声明。

图片体积太大不利于页面加载,建议先压缩后再放入,如果是png图片可考虑使用 TinyPNG – Compress PNG images while preserving transparency