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

既然涉及到文檔合作，那麼最好是能有個像樣的文檔規範之類的東西方便大家更好的合(ㄐㄧㄠ)作(ㄐ一ˋ)，目前想到的有如下幾點。

更新/翻譯特定語言

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 編輯框，右邊爲實時render頁面，可選擇使用全屏模式。

Gitbook Editor

使用其他如 Mou/Vim/Emacs/Sublime Text也不錯，但是在新增Chapter/Section時就比較麻煩了，嗯，你也可以新建 Section 後再使用其他編輯器編輯。

對 Gitbook 不熟的建議看看 Gitbook Documentation，有助於瞭解 http://algorithm.yuanbin.me 網頁上的文字及各章節等是如何編輯及render的。

章節名及編號

章節等文件名全部採用英文，子章節最多到三級，章節編號無需操心，這種瑣事交給 Gitbook 去做就好，如果一定要手動調整，修改SUMMARY.md文件，注意其中的縮排關係，Gitbook就依靠這個自動給章節編號了。

舉個例子，我現在想新增「動態規劃」及其子章節。首先在 Gitbook 頂部menu欄「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, 給出語言類別以便highlight。具體可參看原markdown文件。
  4. 題解中的核心部分對應的程式碼，程式碼中不能明顯看出來的邏輯和一些程式上常用的技巧。
  5. 程式碼順序：Python => C++ => Java 因爲 Python 的程式碼一般最爲簡潔...
  6. 如參考了其他資源，儘可能給出有用的參考鏈接，附簡單的說明。

通過github合作時，添加/修改內容時給出能看懂的commit就好了。暫時就想到這麼多，其實沒那麼多講究啦，感覺看著清楚就好，其他想到的再補充。:-)

數學公式

其實程式碼裡是用不著寫數學公式的，但是偶爾分析演算法可能會用著，用過 LaTeX 的都知道她生成的數學公式有多優雅，以至於不用她來寫數學公式都有點不舒服...

這個文檔裡對於較複雜的數學公式建議使用 LaTeX, 因爲託管在gitbook上，所以就用了輕量級的katex插件，沒有用重量級的 MathJax。行內(inline)和行間公式都是 兩個$, 區別在於行間公式寫到下一行行首，而行內公式不能寫在行首(廢話...)。katex非常脆弱，對一些高級的 LaTeX 語法不支援，否則無法編譯輸出到網站和pdf，儘量用簡單的 LaTeX 語法或者不用。

附件及圖片引用

圖片統一存放在images目錄下，其他附件存放在docs目錄下。引用圖片鏈接一般可以通過![Caption](../../shared-files/images/xxx.png)聲明。

圖片體積太大不利於頁面載入，建議先壓縮後再放入，如果是png圖片可考慮使用 TinyPNG – Compress PNG images while preserving transparency

results matching ""

    powered by

    No results matching ""