From 1f5fa14abfb5c7326af86bffc5d6d739a622b600 Mon Sep 17 00:00:00 2001 From: sshwy Date: Mon, 5 Aug 2019 08:27:46 +0800 Subject: [PATCH] =?utf8?q?=E6=90=AC=E8=BF=90=E5=A4=A7=E9=87=8F=E5=86=85?= =?utf8?q?=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit --- docs/intro/htc.md | 137 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 99 insertions(+), 38 deletions(-) diff --git a/docs/intro/htc.md b/docs/intro/htc.md index 3f0eed24..c1ba3686 100644 --- a/docs/intro/htc.md +++ b/docs/intro/htc.md @@ -4,56 +4,117 @@ OI Wiki 的内容是通过上百位创作者的撰稿、修正,不断地完善 当你打算贡献某部分的内容时,你应该尽量确保: -- 文档内容满足基本格式要求; -- 文档的合理性; -- 文档存储的格式。 +- 文档内容满足基本格式要求; +- 文档的合理性; +- 文档存储的格式。 -### 文档内容的基本格式 - -在提交 PR 前,请先确保文档内容符合下文中的格式要求(如有疑问可以在[How To Contribute](https://github.com/OI-wiki/OI-wiki/wiki/How-to-contribute)页面中查阅相关例子)。格式缺乏基本的规范性、严谨性可能会使你的贡献不能及时通过审核。 - -如果对 mkdocs-material(我们使用的这个主题)还有什么问题,还可以查阅[MkDocs 使用说明](https://github.com/ctf-wiki/ctf-wiki/wiki/Mkdocs-%E4%BD%BF%E7%94%A8%E8%AF%B4%E6%98%8E)和[cyent 的笔记](https://cyent.github.io/markdown-with-mkdocs-material/),前者介绍了 mkdocs-material 主题的插件使用方式,而后者介绍了 markdown 传统语法和 mkdocs-material 支持的扩展语法。 +## 基本格式要求 -#### remark-lint 要求怎样的格式 +### Remark-lint 要求怎样的格式 我们现在启用的配置文件在[.remarkrc](https://github.com/24OI/OI-wiki/blob/master/.remarkrc),它可以自动给项目内文件统一风格。 在配置过程中我们也遇到了一些 remark-lint 不能很好处理的问题: -1. 不要在页面中添加 `

` 或者 `# 标题` 。 -2. `## 简介` 标题要空一格(英文半角空格),也不要写成 `## 简介 ##` 。 -3. 列表 - 1. 列表前要有空行,新开一段。 - 2. `1. 例子` 点号后要有空格。 -4. 行间公式前后各要有一行空行,否则会被当做是行内公式。 -5. 伪代码请使用 ```` ```text```` ,直接使用 ```` ``` ```` 可能导致内容被错误地缩进。 -6. 涉及到目录的更改,需要改动 mkdocs.yml,另外也请注意如果影响到作者信息统计,麻烦更新[author 字段](https://oi-wiki.org/intro/faq/#_15)。 -7. 所有比赛请使用官方正式中文/英文名称。特别注意 NOI 系列赛官方英文名称均为全大写,如 NOIP。 - -#### 文档中 LaTeX 公式的格式 - -- 请不要滥用 LaTeX 公式字体(比如对一些英文单词使用公式字体) -- 对于 LaTeX 公式,请注意常见的问题, **一定要使用** `$\log$` 、 `$\min$` 、 `$\max$` 、 `$\gcd$` 等,而非 `$log$` 、 `$min$` 、 `$max$` 、 `$gcd$` 。对于最小公倍数,请使用 `$\operatorname{lcm}$` 而非 `$lcm$` ,省略号请使用 `$\cdots$` ,叉乘请使用 `$\times$` ,点乘请使用 `$\cdot$` 。其他非数学内容,包括中文、英文、特殊符号等,一律使用 `\text{}` 。 -- 所有公式中的希腊字母等特殊符号,请不要使用输入法的插入特殊符号功能,而应该使用对应的 LaTeX 公式符号。如 phi 大多数情况下应该使用 `$\varphi$` 而不是 `$\phi$` 。 -- 在不会引起歧义的情况下,请用 `\times` 代替星号。如 $a\times b$ ,而不是 $a*b$ 。 -- 请用 `\cdots` , `\ldots` , `\vdots` 代替 `...` 。如 $a_1,a_2,\cdots a_n$ ,而不是 $a_1,a_2,... a_n$ 。 -- 请用 `=` 代替 `==` 。如 $a=b$ ,而不是 $a==b$ 。 -- 请用 `a\bmod b` 代替 `a%b` 。如 $a\bmod b$ ,而不是 $a%b$ 。 -- 为了统一,复杂度分析时大 $O$ 记号请直接使用 `$O()$` 而不要 `$\mathcal O()$` 。 -- 公式中尽量避免中括号而多使用下标。即 $a_{i,j,k}$ 而不是 $a[i][j][k]$ 。在公式中下标较复杂的情况下建议改用多元函数( $f(i,j,k)$ )或内联代码格式。 +1. 不要在页面中添加 `

` 或者 `# 标题` 。 +2. `## 简介` 标题要空一格(英文半角空格),也不要写成 `## 简介 ##` 。 +3. 列表: + 1. 列表前要有空行,新开一段。 + 2. `1. 例子` 点号后要有空格。 +4. 行间公式前后各要有一行空行,否则会被当做是行内公式。 +5. 伪代码请使用 ```` ```text```` ,直接使用 ```` ``` ```` 可能导致内容被错误地缩进。 +6. 涉及到目录的更改,需要改动 mkdocs.yml,另外也请注意如果影响到作者信息统计,麻烦更新[author 字段](https://oi-wiki.org/intro/faq/#_15)。 +7. 所有比赛请使用官方正式中文/英文名称。特别注意 NOI 系列赛官方英文名称均为全大写,如 NOIP。 + +### 标点符号的使用 + +1. 请在每句话的末尾添加**句号**。 +2. 请正确使用标点符号,注意区分**全角**符号与**半角**符号的使用(汉语请使用全角符号,英语请使用半角符号)。 +3. 注意**逗号**的使用(应当使用顿号却使用了逗号等等)。 +4. 注意**括号**的位置。 +5. 请特别注意,我们通常习惯使用 “`「`” 与 “`」`” 来提高**中文引号**的辨识度,同时也常用**分号**来表示列表环境中各复句之间的关系。 + +请参考下面的例子更好地使用标点符号: + + > * 中学生学科竞赛主要包括信息学奥林匹克竞赛、信息学奥林匹克竞赛、信息学奥林匹克竞赛、信息学奥林匹克竞赛和信息学奥林匹克竞赛(我就是这个样,你来打我啊)。 + > * “你吃了吗?”,李四问张三。 + > * 我想对你说:“我真是太喜欢你了。” + > * 「苟利国家生死以,岂因祸福避趋之!」 + > * 推荐题目:「LOJ #104 普通平衡树」 + > * 以下是这个算法的基本流程: + > - 第一步,初始化到各点的距离为无穷大,将所有点设置为未被访问过,初始化一个队列; + > - 第二步,将起点放入队列,将起点设置为已被访问过,更新到起点的距离为 $0$; + > - 第三步,取出队首元素,将该元素设置为未被访问过; + > - 第四步,遍历所有与此元素相连的边,若到这个点存在更短的距离,则进行松弛操作; + > - 第五步,若这个点未被访问过,则将这个点放入队列,且设置这个点为已经访问过; + > - 第六步,回到第三步,直到队列为空。 + +### LaTeX 公式的格式 + +1. 请不要滥用 LaTeX 公式字体(比如对一些英文单词使用公式字体),我们通常使用 LaTeX 公式字体表示变量名称。 + +2. 对于 LaTeX 公式,请注意常见的问题, **一定要使用** `$\log$` 、 `$\min$` 、 `$\max$` 、 `$\gcd$` 等,而非 `$log$` 、 `$min$` 、 `$max$` 、 `$gcd$` 。对于最小公倍数,请使用 `$\operatorname{lcm}$` 而非 `$lcm$` ,省略号请使用 `$\cdots$` ,叉乘请使用 `$\times$` ,点乘请使用 `$\cdot$` 。其他非数学内容,包括中文、英文、特殊符号等,一律使用 `\text{}` 。 + +3. 所有公式中的希腊字母等特殊符号,请不要使用输入法的插入特殊符号功能,而应该使用对应的 LaTeX 公式符号。如 phi 大多数情况下应该使用 `$\varphi$` 而不是 `$\phi$` 。 + +4. 在不会引起歧义的情况下,请用 `\times` 代替星号。如 $a\times b$ ,而不是 $a\ast b$ 。 + +5. 请用 `\cdots` , `\ldots` , `\vdots` 代替 `...` 。如 $a_1,a_2,\cdots a_n$ ,而不是 $a_1,a_2,... a_n$ 。 + +6. 请注意,不要将任何代码的表示方法使用LaTeX公式。例如,使用 `=` 而不是 `==` (如 $a=b$ ,而不是 $a==b$ )、使用`a<<1`或者$a\times 2$而不是 $a<<1$、使用 `a\bmod b` 代替 `a%b` (如 $a\bmod b$ ,而不是 $a%b$ )等。 + +7. 为了统一,复杂度分析时大 $O$ 记号请直接使用 `$O()$` 而不要 `$\mathcal O()$` 。 + +8. 公式中尽量避免中括号而多使用下标。即 $a_{i,j,k}$ 而不是 $a[i][j][k]$ 。在公式中下标较复杂的情况下建议改用多元函数( $f(i,j,k)$ )或内联代码格式。 + +9. LaTeX 作为公式排版的首选,我们应当正确地使用它。首先从使用 Roman 体表示常量和函数做起。LaTeX 已经预先定义好了一些常见的常量、函数、运算符等,我们可以直接调用,包括但不限于: + + ```tex + \log, \ln, \lg, \sin, \cos, \tan, \sec, \csc, \cot, \gcd, \min, \max, \exp, \inf, \mod, \bmod, \pmod + ``` + 所以在输入常量、函数名、运算符等时,请先检查一下是否应该使用 Roman 体或其它字体,LaTeX 符号的书写可参考 [此页](https://katex.org/docs/supported.html) 内容(不是全部),也可以百度求解。 + +10. 如果遇到没有预先定义好的需要使用 Roman 体的**函数名**,我们可以使用 `\operatorname{something}` 来产生,如我们可以使用 `\operatorname{lcm}` 产生正体的最小公倍数(函数)符号。同理,产生 Roman 体的**常量**应用 `\mathrm{}`;其他非数学内容,包括中文、英文、特殊符号等,一律使用 `\text{}`。 + +11. 请不要滥用 LaTeX 公式。这不仅会造成页面加载缓慢(因为 MathJax 的效率低是出了名的),同时也会导致页面的排版混乱。我们的建议是,如非必要,尽量减少公式与普通正文字体的**大量**混合使用,如非必要,尽量不要使用公式,如: + + ``` + 我们将要学习 $Network-flow$ 中的 $SPFA$ 最小费用流,需要使用 $Edmonds-Karp$ 算法进行增广。 + ``` + + 就是一个典型的**滥用公式字体**的例子。 + +12. 请正确使用对应的 LaTeX 符号。如欧拉函数请使用 `\varphi`,圆的直径请使用 `\Phi`,黄金分割请使用 `\phi`。这些符号虽然同样表示希腊字母 Phi,但是在不同的环境下有不同的含义。切记**不要使用输入法的插入特殊符号**来插入这种符号。 + + LaTeX 的省略号请使用 `\cdots`(居于排版基线与顶线中间)或 `\ldots`(居于排版基线的位置),点乘请使用 `\cdot`,叉乘请使用 `\times`。目前,表示 Dirichlet 卷积的符号采用 `*`(参照 Wikipedia)。 + + 另外,由于 LaTeX 历史原因,空集的符号应为 `\varnothing` 而不是 `\emptyset`;由于近百年来数学符号演变,定义集合符号应使用**人民教育出版社 A 版**书写的版本,即 实数集 `\mathbf{R}`,正整数集 `\mathbf{N}^*` 等。同理,其他的符号按照中国国内最常使用的版本来书写,重点参照数学和信息技术课本。 + +13. 请注意您的文档结构。文档结构应当是十分条理的,具有清晰的层次的。请不要让诸如「五级标题」这种事情再次发生了,一篇正常的文章是用不到如此复杂的结构层次的。 + +14. 表示强调时请使用 `**SOMETHING**` 而非某级标题,因为使用标题会导致文章结构层次混乱和(或)目录出现问题。 + +15. 请正确使用 Markdown 的区块功能,插入行间代码请使用一个反引号包围代码区块,行间代码请使用三个反引号包围代码区块,其中反引号就是键盘左上角波浪线下面那个符号。 #### 文档存储的格式 -- **文件名请务必都小写,以 `-` 分割,如 `file-name` 。** -- 请务必确保您的文档中引用的 **外链** 图片已经全部转存到了 **本库内** 对应的 `images` 文件夹中(防止触发某些网站的防盗链),建议处理成 `MD 文档名称 + 编号` 的形式(可参考已有文档中图片的处理方式)。(即格式为 `![](./images/xx.jpg)` )。 -- 请确保您的文档中的引用链接的稳定性, **不推荐** 引用 **自建** 服务(如 OJ)中的资源(如题目) +1. **文件名请务必都小写,以 `-` 分割,如 `file-name` 。** +2. 请务必确保您的文档中引用的 **外链** 图片已经全部转存到了 **本库内** 对应的 `images` 文件夹中(防止触发某些网站的防盗链),建议处理成 `MD 文档名称 + 编号` 的形式(可参考已有文档中图片的处理方式)。(即格式为 `![](./images/xx.jpg)` )。 +3. 请确保您的文档中的引用链接的稳定性, **不推荐** 引用 **自建** 服务(如 OJ)中的资源(如题目) ### 文档的合理性 所谓合理性,指所编写的 **内容** 必须具有如下的特性: -- 由浅入深,内容的难度应该具有渐进性。 -- 逻辑性,对于每类内容的撰写应该尽量包含以下的内容: - - 原理,说明该内容对应的原理。 - - 例子,给出 1 ~ 2 个典型的例子。 - - 题目,在该标题下, **只需要给出题目名字、题目链接** 。 +- 由浅入深,内容的难度应该具有渐进性。 +- 逻辑性,对于每类内容的撰写应该尽量包含以下的内容: + - 原理,说明该内容对应的原理。 + - 例子,给出 1 ~ 2 个典型的例子。 + - 题目,在该标题下, **只需要给出题目名字、题目链接** 。 + +### 文档内容的基本格式 + +在提交 PR 前,请先确保文档内容符合下文中的格式要求(如有疑问可以在[How To Contribute](https://github.com/OI-wiki/OI-wiki/wiki/How-to-contribute)页面中查阅相关例子)。格式缺乏基本的规范性、严谨性可能会使你的贡献不能及时通过审核。 + +如果对 mkdocs-material(我们使用的这个主题)还有什么问题,还可以查阅[MkDocs 使用说明](https://github.com/ctf-wiki/ctf-wiki/wiki/Mkdocs-%E4%BD%BF%E7%94%A8%E8%AF%B4%E6%98%8E)和[cyent 的笔记](https://cyent.github.io/markdown-with-mkdocs-material/),前者介绍了 mkdocs-material 主题的插件使用方式,而后者介绍了 markdown 传统语法和 mkdocs-material 支持的扩展语法。 + -- 2.11.0