Format MD desc and refine the essay. (#3158)
* Update CONTRIBUTING-zh file: format MD desc and refine the essay. * Fix incorrect md syntax. * Refine the zh CONTRIBUTING essay. * update formatting * Fix Travis CI check * Update incorrect formatting * Update formatting * fix travis-ci issuepull/3159/head
parent
19c41b2e81
commit
c10270c034
|
@ -3,12 +3,12 @@
|
||||||
|
|
||||||
## 贡献者许可协议
|
## 贡献者许可协议
|
||||||
|
|
||||||
请遵循此[许可协议](https://github.com/EbookFoundation/free-programming-books/blob/master/LICENSE)参与贡献.
|
请遵循此[许可协议](https://github.com/EbookFoundation/free-programming-books/blob/master/LICENSE)参与贡献。
|
||||||
|
|
||||||
|
|
||||||
## 贡献者行为准则
|
## 贡献者行为准则
|
||||||
|
|
||||||
请同意并遵循此[行为准则](https://github.com/EbookFoundation/free-programming-books/blob/master/CODE_OF_CONDUCT.md)参与贡献.
|
请同意并遵循此[行为准则](https://github.com/EbookFoundation/free-programming-books/blob/master/CODE_OF_CONDUCT.md)参与贡献。
|
||||||
|
|
||||||
|
|
||||||
## 概要
|
## 概要
|
||||||
|
@ -16,17 +16,17 @@
|
||||||
1. "轻易可以下载一本书的链接" 通常都不是 *免费* 书籍的链接。 请只提供免费内容。 确信你所提供的书籍是免费的。我们不接受指向*需要*工作电子邮件地址才能获取书籍的页面的链接,但我们欢迎有需求它们的列表。
|
1. "轻易可以下载一本书的链接" 通常都不是 *免费* 书籍的链接。 请只提供免费内容。 确信你所提供的书籍是免费的。我们不接受指向*需要*工作电子邮件地址才能获取书籍的页面的链接,但我们欢迎有需求它们的列表。
|
||||||
2. 如果你不够了解Git:当你发现了一些有趣的东西 *尚未出现在本仓库* 中,请开一个[Issue](https://github.com/EbookFoundation/free-programming-books/issues)主题讨论。
|
2. 如果你不够了解Git:当你发现了一些有趣的东西 *尚未出现在本仓库* 中,请开一个[Issue](https://github.com/EbookFoundation/free-programming-books/issues)主题讨论。
|
||||||
* 如果你了解Git,请Fork本仓库并提交PR。
|
* 如果你了解Git,请Fork本仓库并提交PR。
|
||||||
3. 这里有5种列表,请选择正确的一个:
|
3. 这里有5种列表,请选择正确的一个:
|
||||||
|
|
||||||
* *Books* : PDF、HTML、ePub、基于一个 gitbook.io的站点、一个Git仓库等等。
|
* *Books* :PDF、HTML、ePub、基于一个 gitbook.io的站点、一个Git仓库等等。
|
||||||
* *Courses* : 课程是一种学习材料,而不是一本书 [This is a course](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/).
|
* *Courses* :课程是一种学习材料,而不是一本书 [This is a course](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/)。
|
||||||
* *Interactive Tutorials* : 一个交互式网站,它允许用户输入代码或命令并对结果进行评估。例如:[Try Haskell](http://tryhaskell.org),[Try Github](http://try.github.io).
|
* *Interactive Tutorials* :一个交互式网站,它允许用户输入代码或命令并对结果进行评估。例如:[Try Haskell](http://tryhaskell.org),[Try Github](http://try.github.io)。
|
||||||
* *Podcasts and Screencasts* : 播客和视频。
|
* *Podcasts and Screencasts* :播客和视频。
|
||||||
* *Problem Sets & Competitive Programming* : 一个网站或软件,让你通过解决简单或复杂的问题来评估你的编程技能,有或没有代码审查,有或没有与其他用户对比结果。
|
* *Problem Sets & Competitive Programming* :一个网站或软件,让你通过解决简单或复杂的问题来评估你的编程技能,有或没有代码审查,有或没有与其他用户对比结果。
|
||||||
|
|
||||||
4. 确保遵循下面的[基本准则](#guidelines),并遵循本仓库文件的[Markdown规定格式](#formatting)。
|
4. 确保遵循下面的[基本准则](#基本准则),并遵循本仓库文件的[Markdown规定格式](#规定格式)。
|
||||||
|
|
||||||
5. Travis CI将运行测试,以确保你的列表是 **按字母顺序排列** 的,并 **遵循格式化规则**。请 **确保** 你的更改通过了该测试。
|
5. Travis CI 将运行测试,以确保你的列表是 **按字母顺序排列** 的,并 **遵循格式化规则**。请 **确保** 你的更改通过了该测试。
|
||||||
|
|
||||||
|
|
||||||
### 基本准则
|
### 基本准则
|
||||||
|
@ -37,7 +37,7 @@
|
||||||
* 使用最权威来源的链接(意思是原作者的网站比编辑的网站好,比第三方网站好)。
|
* 使用最权威来源的链接(意思是原作者的网站比编辑的网站好,比第三方网站好)。
|
||||||
* 没有文件托管服务(包括(但不限于)Dropbox和谷歌驱动器链接)。
|
* 没有文件托管服务(包括(但不限于)Dropbox和谷歌驱动器链接)。
|
||||||
* 优先选择使用 `https` 链接,而不是 `http` 链接 -- 只要它们位于相同的域并提供相同的内容。
|
* 优先选择使用 `https` 链接,而不是 `http` 链接 -- 只要它们位于相同的域并提供相同的内容。
|
||||||
* 在根域上,去掉末尾的斜杠:使用 `http://example.com` 代替 `http://example.com/`
|
* 在根域上,去掉末尾的斜杠:使用 `http://example.com` 代替 `http://example.com/`。
|
||||||
* 总是选择最短的链接:使用 `http://example.com/dir/` 比使用 `http://example.com/dir/index.html` 更好。
|
* 总是选择最短的链接:使用 `http://example.com/dir/` 比使用 `http://example.com/dir/index.html` 更好。
|
||||||
* no URL shortener links <!-- 待翻译 -->
|
* no URL shortener links <!-- 待翻译 -->
|
||||||
* 优先选择使用 "current" 链接代替有 "version" 链接:使用 `http://example.com/dir/book/current/` 比使用 `http://example.com/dir/book/v1.0.0/index.html` 更好。
|
* 优先选择使用 "current" 链接代替有 "version" 链接:使用 `http://example.com/dir/book/current/` 比使用 `http://example.com/dir/book/v1.0.0/index.html` 更好。
|
||||||
|
@ -49,7 +49,7 @@
|
||||||
* 如果一个资源存在于Internet上的不同位置
|
* 如果一个资源存在于Internet上的不同位置
|
||||||
* 使用最权威来源的链接(意思是原始作者的网站比编辑的网站好,比第三方网站好)。
|
* 使用最权威来源的链接(意思是原始作者的网站比编辑的网站好,比第三方网站好)。
|
||||||
* 如果它们链接到不同的版本,你认为这些版本差异很大,值得保留,那么添加一个单独的链接,并对每个版本做一个说明(参见[Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353)有助于格式化问题的讨论)。
|
* 如果它们链接到不同的版本,你认为这些版本差异很大,值得保留,那么添加一个单独的链接,并对每个版本做一个说明(参见[Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353)有助于格式化问题的讨论)。
|
||||||
* 相较一个比较大的提交,我们更倾向于原子提交(通过添加/删除/修改进行一次提交)。在提交PR之前没有必要压缩你的提交。(我们永远不会执行这个规则,因为这只是维护人员的方便)
|
* 相较一个比较大的提交,我们更倾向于原子提交(通过添加/删除/修改进行一次提交)。在提交PR之前没有必要压缩你的提交。(我们永远不会执行这个规则,因为这只是维护人员的方便)。
|
||||||
* 如果一本书比较旧,请在书名中注明出版日期。
|
* 如果一本书比较旧,请在书名中注明出版日期。
|
||||||
* 包含作者的名字或适当的名字。中文版本可以用 “等” 缩短作者列表。
|
* 包含作者的名字或适当的名字。中文版本可以用 “等” 缩短作者列表。
|
||||||
* 如果一本书还没有完成,并且仍在编写中,则需添加 “编写中” 符号,参见[下文](#in_process)所述。
|
* 如果一本书还没有完成,并且仍在编写中,则需添加 “编写中” 符号,参见[下文](#in_process)所述。
|
||||||
|
@ -58,17 +58,22 @@
|
||||||
|
|
||||||
### 规定格式
|
### 规定格式
|
||||||
|
|
||||||
* 所有列表都是`.md`文件。试着学习[Markdown](https://guides.github.com/features/mastering-markdown/)语法。很容易上手!
|
* 所有列表都是`.md`文件。试着学习[Markdown](https://guides.github.com/features/mastering-markdown/)语法。它很容易上手!
|
||||||
* 所有的列表都以索引开始。它的作用是列出并链接所有的部分或子部分。请按照字母顺序排列。
|
* 所有的列表都以索引开始。它的作用是列出并链接所有的sections(章节/段落)或subsections(子段落/子章节)。务必遵循字母顺序排列。
|
||||||
* Sections(章节/段落)使用3级标题(`###`), subsections(子段落/自章节)使用4级标题 (`####`).
|
* Sections(章节/段落)使用3级标题(`###`),subsections(子段落/子章节)使用4级标题 (`####`)。
|
||||||
整体思想为:
|
|
||||||
|
|
||||||
|
#### 整体思想为:
|
||||||
|
|
||||||
* `2` :新添加的Section与末尾链接间必须留有`2`个空行
|
* `2` :新添加的Section与末尾链接间必须留有`2`个空行
|
||||||
* `1` :标题和第一个链接之间必须留有`1`个空行的空行
|
* `1` :标题和第一个链接之间必须留有`1`个空行的空行
|
||||||
* `0` :任何两个链接之间不能留有任何空行
|
* `0` :任何两个链接之间不能留有任何空行
|
||||||
* `1` :每个`.md`文件末尾必须留有`1`个空行
|
* `1` :每个`.md`文件末尾必须留有`1`个空行
|
||||||
举例:
|
|
||||||
|
|
||||||
```md
|
|
||||||
|
#### 举例:
|
||||||
|
|
||||||
|
```
|
||||||
[...]
|
[...]
|
||||||
* [一本很有用的书](http://example.com/example.html)
|
* [一本很有用的书](http://example.com/example.html)
|
||||||
(空行)
|
(空行)
|
||||||
|
@ -86,7 +91,7 @@
|
||||||
正确:* [一本很有用的书](http://example.com/book.html)
|
正确:* [一本很有用的书](http://example.com/book.html)
|
||||||
```
|
```
|
||||||
|
|
||||||
* 如果包括作者,请使用' - '(由单个空格包围的破折号):
|
* 如果包括作者,请使用' - '(由单个空格(英文半角)包围的破折号):
|
||||||
|
|
||||||
```
|
```
|
||||||
错误:* [一本很有用的书](http://example.com/book.html)- 张显宗
|
错误:* [一本很有用的书](http://example.com/book.html)- 张显宗
|
||||||
|
@ -100,6 +105,13 @@
|
||||||
正确:* [一本很有用的书](https://example.org/book.pdf) (PDF)
|
正确:* [一本很有用的书](https://example.org/book.pdf) (PDF)
|
||||||
```
|
```
|
||||||
|
|
||||||
|
* 如需备注或注解,请使用英文半角括号`( )`:
|
||||||
|
|
||||||
|
```
|
||||||
|
错误:* [一本很有用的书](https://example.org/book.pdf) (繁体中文)
|
||||||
|
正确:* [一本很有用的书](https://example.org/book.pdf) (繁体中文)
|
||||||
|
```
|
||||||
|
|
||||||
* 作者在电子书格式之前:
|
* 作者在电子书格式之前:
|
||||||
|
|
||||||
```
|
```
|
||||||
|
@ -115,6 +127,14 @@
|
||||||
正确:* [一本很有用的书](http://example.com/) - 张显宗 (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html)
|
正确:* [一本很有用的书](http://example.com/) - 张显宗 (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html)
|
||||||
```
|
```
|
||||||
|
|
||||||
|
* 多作者,多译者时,请使用中文 `、` 进行分隔,在译者名字后请使用英文半角括号包围的 `(翻译)`,可以用 “等” 缩短作者列表:
|
||||||
|
|
||||||
|
```
|
||||||
|
错误:* [一本很有用的书](https://example.org/book.pdf) - 张显宗,岳绮罗
|
||||||
|
正确:* [一本很有用的书](https://example.org/book.pdf) - 张显宗、岳绮罗(翻译)
|
||||||
|
正确:* [一本很有用的书](https://example.org/book.pdf) - 张显宗、岳绮罗、顾玄武、出尘子 等
|
||||||
|
```
|
||||||
|
|
||||||
* 在旧书的标题中包括出版年份:
|
* 在旧书的标题中包括出版年份:
|
||||||
|
|
||||||
```
|
```
|
||||||
|
@ -123,7 +143,7 @@
|
||||||
```
|
```
|
||||||
|
|
||||||
<a name="in_process"></a>
|
<a name="in_process"></a>
|
||||||
* 编写(翻译)中的书籍
|
* 编写(翻译)中的书籍:
|
||||||
|
|
||||||
```
|
```
|
||||||
正确:* [马上出版的一本书](http://example.com/book2.html) - 张显宗 (HTML) (:编著状态: *编写中*)
|
正确:* [马上出版的一本书](http://example.com/book2.html) - 张显宗 (HTML) (:编著状态: *编写中*)
|
||||||
|
|
Loading…
Reference in New Issue