gaspersic/free-programming-books
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs(contributing): Homogenize format across translated files (#6625)

Browse Source 
* docs(contributing): remove trailing spaces

* docs(contributing): Apply headings `2-1` empty lines lint rule

* docs(contributing): Apply headings `2-1` empty lines lint rule

forgotten in previous commit: e83220aa4c

* docs(contributing): Move anchor alias to inside list items

... there where an anchor alias `<a name="...">` is used near to each of those list items

This solves markdownlint `MD032/blanks-around-lists` issue

* docs(contributing): Homogenize `1` blank line in nutshell enumeration

* docs(contributing): Homogenize `1` blank line inside Formatting section

* docs(contributing): Ensure `4-spaces` indent `.editorconfig` param

* docs(contributing): Homogenize format & indent of code blocks

- Format using fenced style.
- Well indent in those placed inside list enumerations.
- Simulate `Good` - `Bad` monospace double colon indent inside each one.

- Examples highlighting as `text-plain`. The `md, markdown` style doesn't work very well since blocks has mixed syntax.
- `check_urls` code block highlighted as `properties` style (key-value pair).

Solves markdownlint rules:
- MD040/fenced-code-language: Fenced code blocks should have a language specified
- MD046/code-block-style: Code block style [Expected: indented; Actual: fenced]

* docs(contributing): Ensure `4-spaces` indent `.editorconfig` param

Forgotten in commit: 31c776cb52

* docs(contributing): Homogenize format & indent of code blocks

- Simulate `Good` - `Bad` monospace double colon indent inside each one.

Revert commit f9dc719aef only in this file after check non-needs in a deployed web snapshot

* docs(contributing): Use "consistent" unordered list mark

Solves markdownlint rules:
MD004/ul-style: Unordered list style "consistent"

* docs(contributing): Solve `no-space-in-*` lint rules

markdownlint rules:
MD037/no-space-in-emphasis: Spaces inside emphasis
MD038/no-space-in-code: Spaces inside code span elements
MD039/no-space-in-links: Spaces inside link text

* docs(contributing): Move some punctuation just before any closing brackets after it

* docs(contributing): Hack highlight IDE/Editors headings+HTML

It apply the hack to highlight in IDE/Editors those headings with an anchor alias just before itself

* docs(contributing): Homogenize Pull Request acronym

* docs(contributing): Fix `GitHub` trademark typos

* docs(contributing): ALLCAPS

* docs(contributing): Git trademark

* docs(contributing): YouTube trademark

* docs(contributing): ISBN acronym

* fix: flag emoji code `en` > `us`

Resolves d775cb34fb (commitcomment-59537594)

#5831: `:en:` emoji flag markup doesn't work. Use `🇺🇸` 🇺🇸 or `🇬🇧` 🇬🇧

d775cb34fb (diff-b35eb40c148657d4ea1361c44496e11c5625f484a4c6040c022770e88cbcfdccR8-R10)

* docs(contributing): Fix fa_IR broken anchors

* docs(contributing): filenames in monospace font

* docs(contributing): Homogenize `check_urls=file_to_check`

* docs(contributing): literals/markup texts in monospace font

- `et al.`
- File extensions `.md`
- Protocols: `http`, `https`...
- Notes: LeanPub, require email, StackOverflow, in process, archived

trailing dots in that lines

* docs(contributing): linkify wayback machine

* docs(contributing): Fix `Leanpub` trademark typos

* chore: Rename `master` to `main` #blacklivesmatter

Resolves EbookFoundation/free-programming-books#5803

* docs(contributing): fix broken ref link to `programming-playgrounds`

Fix over EbookFoundation/free-programming-books#5449 and commit 3c42c3629e

(cherry picked from commit 59ebfe3f97e318fa43d58877cbc5bfdd8b0c7426)

* docs(contributing): fix repo urls on initial FR translation

- `ElivreFoundation` -> `EbookFoundation`
- `free-programming-livres` ->`free-programming-books`

PR: #5554
Commit: e629db6b05

Affected lines: 
- 18bb745c90 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R4) // e629db6b05 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R4)
- 18bb745c90 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R7) // e629db6b05 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R7)
- 18bb745c90 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R13) // e629db6b05 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R13)
- 18bb745c90 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R45) // e629db6b05 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R45)

* docs(contributing): use relative urls EN

Via #6614

* docs(contributing): greek. place translations link in right place

Via #6614

* Merge EbookFoundation/free-programming-books#6631 upstream/main commit into docs/contributing/sync/1

* Add repo badges (see EbookFoundation/free-programming-books#5983)

(cherry picked from a16a79b12d solving merge conflict)

* Merge EbookFoundation/free-programming-books#6662 upstream/main commit into docs/contributing/sync/1

* Apply centering proposed at #5983 but not implemented in #6631

(cherry picked from commit f36fd03c06)

* format(contributing): Bold 5th nutshell equal zh

* Merge #6677 upstream/main commit into docs/contributing/sync/1

fix(docs): Use Kramdown processor (#6677)
* Update _config.yml
* add markdown="1"
* update url
* complete removing spaces?
* explicitly use kramdown

(cherry picked from commit de2f31976f)
This commit is contained in:
David Ordás
2022-02-03 02:39:27 +01:00
committed by GitHub
parent ef5d68b85c
commit 84438cb1df
15 changed files with 1167 additions and 923 deletions
Download Patch File Download Diff File Expand all files Collapse all files

105
docs/CONTRIBUTING-zh.md
View File

@ -14,19 +14,21 @@
## 概要
1. "一个可以轻易下载一本书的链接" 并不代表它指向的就是 *免费* 书籍。 请只提供免费内容。 确信你所提供的书籍是免费的。我们不接受指向*需要*工作电子邮件地址才能获取书籍的页面的链接，但我们欢迎有需求它们的列表。
2. 你不需要会 Git：如果你发现了一些有趣的东西 *尚未出现在本仓库* 中，请开一个[Issue](https://github.com/EbookFoundation/free-programming-books/issues)进行主题讨论。
* 如果你已经知晓Git，请Fork本仓库并提交PR。
* 如果你已经知晓Git，请Fork本仓库并提交Pull Request (PR)。
3. 这里有5种列表，请选择正确的一个：
* *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/)。
* *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* ：播客和视频。
* *Problem Sets & Competitive Programming* ：一个网站或软件，让你通过解决简单或复杂的问题来评估你的编程技能，有或没有代码审查，有或没有与其他用户对比结果。
4. 确保遵循下面的[基本准则](#基本准则)，并遵循本仓库文件的[Markdown规定格式](#规定格式)。
5. Github Actions 将运行测试，以确保你的列表是 **按字母顺序排列** 的，并 **遵循格式化规则**。请 **确保** 你的更改通过了该测试。
5. GitHub Actions 将运行测试，以确保你的列表是 **按字母顺序排列** 的，并 **遵循格式化规则**。请 **确保** 你的更改通过了该测试。
### 基本准则
@ -42,17 +44,17 @@
* 不要提供短链接
* 优先选择使用 "current" 链接代替有 "version" 链接：使用 `http://example.com/dir/book/current/` 比使用 `http://example.com/dir/book/v1.0.0/index.html` 更好。
* 如果一个链接存在过期的证书/自签名证书/SSL问题的任何其他类型：
1. *replace it* ：如果可能的话，将其 *替换* 为对应的`http`(因为在移动设备上接受异常可能比较复杂)。
2. *leave it* ：如果没有http版本，但仍然可以通过https访问链接，则在浏览器中添加异常或忽略警告。
3. *remove it* ：上述以外删除掉它。
1. *replace it* ：如果可能的话，将其 *替换* 为对应的`http`(因为在移动设备上接受异常可能比较复杂)。
2. *leave it* ：如果没有`http`版本，但仍然可以通过`https`访问链接，则在浏览器中添加异常或忽略警告。
3. *remove it* ：上述以外删除掉它。
* 如果一个链接以多种格式存在，请添加一个单独的链接，并注明每种格式。
* 如果一个资源存在于Internet上的不同位置
* 使用最权威来源的链接(意思是原始作者的网站比编辑的网站好，比第三方网站好)。
* 如果它们链接到不同的版本，你认为这些版本差异很大，值得保留，那么添加一个单独的链接，并对每个版本做一个说明(参见[Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353)有助于格式化问题的讨论)。
* 相较一个比较大的提交，我们更倾向于原子提交(通过添加/删除/修改进行一次提交)。在提交PR之前没有必要压缩你的提交。(我们永远不会执行这个规则，因为这只是维护人员的方便)。
* 如果一本书比较旧，请在书名中注明出版日期。
* 包含作者的名字或适当的名字。中文版本可以用 “等” 缩短作者列表。
* 如果一本书还没有完成，并且仍在编写中，则需添加 “编写中” 符号，参见[下文](#in_process)所述。
* 包含作者的名字或适当的名字。中文版本可以用 “`等`” (“`et al.`”) 缩短作者列表。
* 如果一本书还没有完成，并且仍在编写中，则需添加 “`in process`” 符号，参见[下文](#in_process)所述。
* 如果在开始下载之前需要电子邮件地址或帐户设置，请在括号中添加合适的语言描述，例如：`(*需要*电子邮件，但不是必须的)`。
@ -62,18 +64,16 @@
* 所有的列表都以索引开始。它的作用是列出并链接所有的sections(章节/段落)或subsections(子段落/子章节)。务必遵循字母顺序排列。
* Sections(章节/段落)使用3级标题(`###`)，subsections(子段落/子章节)使用4级标题 (`####`)。
#### 整体思想为：
整体思想为：
* `2` ：新添加的Section与末尾链接间必须留有`2`个空行
* `1` ：标题和第一个链接之间必须留有`1`个空行的空行
* `0` ：任何两个链接之间不能留有任何空行
* `1` ：每个`.md`文件末尾必须留有`1`个空行
举例：
#### 举例：
```
```text
[...]
* [一本很有用的书](http://example.com/example.html)
(空行)
@ -86,66 +86,65 @@
* 在 `]` 和 `(` 之间不要留有空格：
```
错误：* [一本很有用的书] (http://example.com/book.html)
正确：* [一本很有用的书](http://example.com/book.html)
```
```text
错误：* [一本很有用的书] (http://example.com/book.html)
正确：* [一本很有用的书](http://example.com/book.html)
```
* 如果包括作者，请使用' - '(由单个空格(英文半角)包围的破折号)：
```
错误：* [一本很有用的书](http://example.com/book.html)- 张显宗
正确：* [一本很有用的书](http://example.com/book.html) - 张显宗
```
```text
错误：* [一本很有用的书](http://example.com/book.html)- 张显宗
正确：* [一本很有用的书](http://example.com/book.html) - 张显宗
```
* 在链接和电子书格式之间放一个空格：
```
错误：* [一本很有用的书](https://example.org/book.pdf)(PDF)
正确：* [一本很有用的书](https://example.org/book.pdf) (PDF)
```
```text
错误：* [一本很有用的书](https://example.org/book.pdf)(PDF)
正确：* [一本很有用的书](https://example.org/book.pdf) (PDF)
```
* 如需备注或注解，请使用英文半角括号`( )`：
```
错误：* [一本很有用的书](https://example.org/book.pdf) （繁体中文）
正确：* [一本很有用的书](https://example.org/book.pdf) (繁体中文)
```
```text
错误：* [一本很有用的书](https://example.org/book.pdf) （繁体中文）
正确：* [一本很有用的书](https://example.org/book.pdf) (繁体中文)
```
* 作者在电子书格式之前：
```
错误：* [一本很有用的书](https://example.org/book.pdf)- (PDF) 张显宗
正确：* [一本很有用的书](https://example.org/book.pdf) - 张显宗 (PDF)
```
```text
错误：* [一本很有用的书](https://example.org/book.pdf)- (PDF) 张显宗
正确：* [一本很有用的书](https://example.org/book.pdf) - 张显宗 (PDF)
```
* 多重格式：
```
错误：* [一本很有用的书](http://example.com/)- 张显宗 (HTML)
错误：* [一本很有用的书](https://downloads.example.org/book.html)- 张显宗 (download site)
正确：* [一本很有用的书](http://example.com/) - 张显宗 (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html)
```
```text
错误：* [一本很有用的书](http://example.com/)- 张显宗 (HTML)
错误：* [一本很有用的书](https://downloads.example.org/book.html)- 张显宗 (download site)
正确：* [一本很有用的书](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) - 张显宗、岳绮罗、顾玄武、出尘子 等
```
```text
错误：* [一本很有用的书](https://example.org/book.pdf) - 张显宗，岳绮罗
正确：* [一本很有用的书](https://example.org/book.pdf) - 张显宗、岳绮罗(翻译)
正确：* [一本很有用的书](https://example.org/book.pdf) - 张显宗、岳绮罗、顾玄武、出尘子 等
```
* 在旧书的标题中包括出版年份：
```
错误：* [一本很有用的书](https://example.org/book.html) - 张显宗 - 1970
正确：* [一本很有用的书 (1970)](https://example.org/book.html) - 张显宗
```
```text
错误：* [一本很有用的书](https://example.org/book.html) - 张显宗 - 1970
正确：* [一本很有用的书 (1970)](https://example.org/book.html) - 张显宗
```
<a name="in_process"></a>
* 编写(翻译)中的书籍：
* <a name="in_process"></a>编写(翻译)中的书籍：
```
正确：* [马上出版的一本书](http://example.com/book2.html) - 张显宗 (HTML) (:construction: *编写中*)
正确：* [马上出版的一本书](http://example.com/book2.html) - 张显宗 (HTML) (:construction: *翻译中*)
```
```text
正确：* [马上出版的一本书](http://example.com/book2.html) - 张显宗 (HTML) (:construction: *编写中*)
正确：* [马上出版的一本书](http://example.com/book2.html) - 张显宗 (HTML) (:construction: *翻译中*)
```