Help:Style (简体中文) - ArchWiki

# Help:Style (简体中文)

相关文章

- Help:Style/Formatting and punctuation
- Help:Style/White space
- Help:Editing
- Help:Reading
- Help:Discussion
- Help:Template

翻译状态： 本文是英文页面 Help:Style 的翻译，最后翻译时间：2014-12-02，点击这里可以查看翻译后英文页面的改动。

这些风格约定鼓励简约、有条理和视觉一致的文章。请在编辑 ArchWiki 时尽量遵守本文的指导。

## 文章页面

### 标题

- 标题应该首字母大写, 例如应该使用 "Title for new page" 而不是 "Title for New Page"。如果单词是常见缩写的一部分，则应该使用大写，例如应该使用 "Advanced Linux Sound Architecture" 而不是 "Advanced Linux sound architecture".
  名称空间不是标题的一部分，应该使用"ArchWiki:Example article" 而不是 "ArchWiki:example article"。子页面名也应该首字母大写，应该使用 "My page/My subpage" 而不是"My pagee/my subpage".
- 使用全名而不是缩写。如果您认为它们都很常见，可创建一个从缩写到全名的重定向 。不要用括号包含缩写。
- 参见 文章命名指导。

### 布局

ArchWiki 上的文章应该分为两部分：前言和主体，且主要遵循如下顺序：

- 前言：由分类、i18n、文章状态、概览和简介
- 主体: 介绍、安装、配置、技巧、问题解决和更多内容

- 文章各部分的排列顺序应该为:

1. #特殊字段 (可选)
2. #分类
3. #语言间链接
4. #文章状态模板 (可选)
5. #相关文章 (可选)
6. #前言或介绍
7. 目录 (自动生成)
8. 文章特有的部分

### 特殊字段

- 特殊字段会修改文章的显示方式，但并不会添加内容。这些字段应该位于文章的最开始，尤其是这两个：`{{DISPLAYTITLE:title}}` 和 Template:Lowercase title。

### 分类

- 每个文章至少应该属于一个分类。
- 一个文章可以属于多个分类，只要分类间没有包含关系。
- 分类必须放在文章的顶部，且在特殊字段之后。

注意: 这点和其它 MediaWiki 项目有时会不一样，后者经常把分类放在文章末尾。

- 分类与正文第一段（包括语言间链接）之间不要插入空格，否则会有多余的空白。
- 参见 文章分类。

小贴士:

- 由于分类页面中，MediaWiki会把相同首字母的页面归到一栏中，对于中文标题的页面，会把每个起始汉字归到一类，导致页面很混乱。因此在为名称由中文起始的页面，添加分类时请同时添加汉语拼音的首字母，如官方安装指南可以添加如下分类：`[[Category:简体中文|G]]`，这样该页面就会归类到字母G一栏的最上方。
- 不要添加多个字母(如：`[[Category:简体中文|GFAZZN]]`)，否则会出现分类中中英文页面顺序混排的现象，使页面不便于查找。

### 语言间链接

- 如果文章有其他语言的翻译，必须在分类和正文第一段之间加上這些语言间链接。它们将显示在页面的左边。
- 语言间链接和正文第一段之间不应该有空格，否则文章顶部会有多余的空白。
- 除了在当前页面上添加其它语言间链接，您还需要在其它语言的页面上添加当前页面的语言间链接。
- 每个语言的语言间链接应只能有一个。
- 不要加入当前语言的语言间链接。
- 语言间链接需要根据其语言标签，來按字母表顺序排列，不要按语言本身的正式名稱顺序排列。例如，`` 就该排在 `` 前面，哪怕 “Suomi” 就本来在 “Français” 之后。
- 参见 Help:i18n 和 Wikipedia:Help:Interlanguage links.

### 文章状态模板

- 文章状态模板 应放在分类(或语言间链接)和相关文章之间。
- 文章的某段落也可以使用文章状态模板。
- 每个状态模版都应该包含简要的说明。有必要时，可以在讨论页面加以讨论。

### 相关文章

- 给出相关的文章列表
- 放在分类、语言间链接和文章状态模板之后。
- 通过组合模板 Template:Related articles start (简体中文), Template:Related 和 Template:Related articles end 实现。详情参阅这几个模板的页面。
- 可以使用 Template:Related2 给出需要显示的标题翻译.
- 如果文章较多，或者需要详细描述，请使用参阅段落。

### 前言或介绍

- 描述文章的话题。
  不要自己给软件下评论，一般可以访问项目主页，使用作者自己的描述。MediaTomb 是一个范例。
- 放在第一段前面
- 不要另外加上 `==Introduction==` 或 `==Preface==` 说明：直接在第一段开始时写入即可。如果文章有足够多的段落，在前言和第一段直接会自动加入目录。
- 参见 Writing Article Introductions。

### 段落标题

- 段落标题应该从第二级开始(`==`), 因为第一级已保留给文章标题用。
- 使用子标题时不要越级，就像二级标题下面必然是三级标题。
- 不要在标题上添加超链接，它们会破坏样式的一致性。
  同理，请不要使用任何 html 或 wiki 标记代码，包括 #代码格式。
- 参见 Effective Use of Headers。

### 代码格式

- 使用 `{{ic|code}}` 格式化要嵌入的微代码、文件名、命令名、变量名等。例如:
  在终端运行`sh ./hello_world.sh`
- 对于单行的代码 (命令行或者代码输出) 可以可以直接在行首加入空格，参考Help:Editing#Code. 示例：

    $ sh ./hello_world.sh

    Hello World

- 使用 `{{bc|code}}` 格式化多行代码(命令行的输入或输出内容、文件内容) 例如:

    #!/bin/sh

    # Demo
    echo "Hello World"

- 如果代码不长，代替 `{{bc|code}}` (参见 编辑帮助)。
- 使用 `{{hc|input|output}}` 能同时显示命令行及其输出，例如:

    $ sh ./hello_world.sh

    Hello World

- 需要显示文件内容时，可以使用 `{{hc|filename|content}}` 明确内容属于哪个文件，例如：

    ~/hello_world.sh

    #!/bin/sh

    # Demo
    echo "Hello World"

- 大段的代码，例如配置文件，可以考虑用 `...` 略去无关的内容
- 关于模板的一些格式上的特殊处理，比如`=` 或 `|`，请阅读 Help:Template。

### 命令行文字

- 使用段落代码 (Template:bc) 时，需要提示符标注执行权限;使用 Template:ic 时不需要提示符，但是需要用文字明确指出需要的权限。
- 使用 `$` 作为一般用户权限命令的提示符；使用 `#` 作为 root 命令的提示符。
  注意: 因为 `#` 也经常表示文本文件中的注释符号，所以经常要澄清是运行命令还是编辑文件，以避免不必要的误解。
- 引入命令的句子尽量以 `:` 结尾。
- 建议使用 `# command` 而不是 `$ sudo command`。
- 尽量少假设用户会使用 `sudo` 或其它权限获取工具(例如 `gksu`、`kdesu`)。
- 应该避免`# sudo command`，唯一的例外是用`sudo`的`-u`选项修改用户，这时提示符可以与其它命令一致，默认使用`$`。
- 不要在一行命令的代码框里添加注释，例如`# pacman -S foo #Install package foo`就不好
- 代码行不要过长，请尽量换行。

### 文件编辑需求

- 除非必要，请不要特别指定某编辑器(nano, vim, emacs, ...)。
- 除非必要，请不要使用隐晦复杂的编辑命令，就像 `$ echo -e "clear\nreset" >> ~/.bash_logout` 应该写成这样：

  将下行附加到 `~/.bash_logout`:

      clear
      reset

### 键盘按键

- 表示按键的标准方法是使用 Template:Ic 模板。
- 字母键应该小写：`a`. 大写字母用 `Shift+a`，不要使用 `Shift+A` 或 `A`。
- 表示按键组合的正确方法是使用 `+` 号连接，不要增加额外空格，在一个模板中包含多个按键：`Ctrl+c`.
  下面格式都应该避免使用：`Ctrl + c`, `Ctrl`+`c`, `Ctrl-c`。
- 特殊键的标准名称：
  - `Shift` (不要用 `SHIFT`)
  - `Ctrl` (不要用 `CTRL` 或 `Control`)
  - `Alt` (不要用 `ALT`)
  - `Super` (不要用 `Windows` 或 `Mod`)
  - `Enter` (不要用 `ENTER` 或 `Return`)
  - `Esc` (不要用 `ESC` 或 `Escape`)
  - `Space` (不要用 `SPACE`)
  - `Backspace`
  - `Tab`
  - `Ins` (不要用 `INS` 或 `Insert`)
  - `Del` (不要用 `DEL` 或 `Delete`)
  - `Print Screen`
  - `PageUp`
  - `PageDown`

### 软件包管理

#### 官方软件包

- 在示意要从官方软件仓库安装软件包时，请避免直接标出 pacman 命令。不仅简化内容(每个 Arch 用户都应该知道如何使用 pacman)而且避免了 `pacman -Sy package` 之类的键误，以及 `pacman -S package` 和 `pacman -Syu package` 孰好孰坏的无谓争论。同理，也不要引进 pacman 前端或图形界面等。
  相反，请像这样简单地示范：安装说明应该使用：
  安装位于官方软件仓库的 package。
  Wiki 代码则是 `[[pacman (简体中文)|安装]]位于[[Official repositories (简体中文)|官方软件仓库]]的 {{Pkg|package}}`
  安装一系列软件包的示范则应该是:
  安装位于官方软件仓库的 package1、package2 和 package3。
  有必要时，可酌情修改语句。
- 必须要用 Template:Pkg 模板把软件包超链接化，例如`{{Pkg|package}}`.
- 上例中同时给出了 pacman 的隐性链接 (`[[pacman (简体中文)|安装]] ...`) 和 官方软件仓库 的链接(`[[official repositories]]`): 建议至少在文章的第一个安装指令中用到这些链接，尤其是 Arch 新手经常浏览的页面。
- 在新手指南中推荐使用 pacman 命令，新用户还不太熟练。
- 不要特意指出软件包是在 [core]、[extra] 或 [community] 中的哪一个仓库，因为一个软件包可能会在不同仓库之间转移。此外如果软件包位于 [multilib] 仓库，请这样示范：
  安装官方软件仓库的 package 时，需要实现开启 multilib 仓库。

#### AUR 软件包

- 安装 AUR 软件包的语句应该类似于安装官方软件包的示范：
  安装 AUR 中的 package。
  Wiki 文字为 `安装 [[Arch User Repository (简体中文)|AUR]] 中的 {{AUR|package}}。`
  可以适当修改以适应具体文章，但是一定要明确指出软件包并非官方支持。
- 千万不要直接示范如何安装 AUR 软件包：因为凡是安装非官方软件包的用户，都得事先充分阅读 Arch 用户仓库，并了解使用这些包会给系统带来的风险。
- AUR 软件包的超链接化应该使用 Template:AUR 模版，例如 `{{AUR|package}}`.

#### 非官方软件仓库

- 要使用非官方软件仓库时，请先将其加入非官方软件仓库，然后提供一个链接，示例：
  从AUR 或者 示例 软件仓库安装 package.
  不要在文章内直接给出启用软件仓库的详细信息。
- 必须链接到 非官方软件仓库，而且请尽量使用段落链接：`[[Unofficial User Repositories#example|example]]`.

### 内核模块操作

- 不要举例说明如何加载、删除、屏蔽等，正确的说明方法是列出所涉及模块、依赖模块和冲突模块，加以描述要执行的动作，最后再补充上 Kernel modules (简体中文) 的链接。
- 新手指南毋须遵守该规范。

### Systemd 单元操作

- 不要用systemctl 命令直接进行 start、 restart 或 stop 的操作。正确的说明方法应该是列出需要的单元，以及它们的依赖、冲突关系，描述所要执行的操作。例如：

    要在开机时启动 GDM，请 启用 `gdm.service`.
  如果模板需要实例化：
    要在无线时自动切换 netctl 配置，启用 一个带接口名称的 `netctl-auto@.service` 实例，例如 `netctl-auto@wlan0.service`.
  可以根据上下文调整语句，但是请确保有到 systemd#Using units 文章段落的链接，可以直接引用或通过 重定向 实现，例如 `[[start]]`, `[[enable]]` or `[[stop]]`.

- 新手指南 同样毋须遵守该规范，建议直接使用systemctl。

### 注意, 警告, 技巧

- 注意 应该用在用户预料不到的地方。包括与文章关系不大的细节知识、软件包名称变动等。
  也可以用来强调容易被用户忽略的地方。
- 警告 用来指出需要特别警惕的地方，比如不可逆转的修改、损害系统的可能性等。警告应该直接指出最坏的情况，并给出相应措施。不要滥用警告，如果不确定的时候，用注意即可。
- 小贴士 用来给出一个可能会相当有用的小技巧，一般不是必须的，省略也无妨。
- 如果多个注意、警告、技巧连用，最好组合到单一模板中，除非彼此毫无相干。例如:

  小贴士:
  - Tip example #1.
  - Tip example #2.

### Shells

- 除非必要，不要特别指定用户所用的 shell：撰写文章内容时请尽量做到与所用 shell 无关。

### 超链接

- 尽可能在该页面和相关页面插入彼此的超链接，实现 wiki 脉络性最大化。
- 像 系统调用 之类的文章 ArchWiki 却没有，大可直接用到 Wikipedia 页面的链接。
- 链接到 wiki 中其它页面时，不要用完整地址，而是用 wiki 间链接语法：`[[Wiki Article]]`。 wiki 引擎可以跟踪 wiki 间链接，好让大家更容易维护。
  更多 wiki 间链接内容参见 Help:Editing (简体中文)#链接。
- 请避免使用隐含链接，例如应该使用"参阅 systemd。" 而不是 "参阅 here".
- 除极个别情况外，页面不能是死亡页面(没有任何到其它页面的链接)或孤立页面(没有其它文章链接到它).
- 添加内容时，首先请注意是不是已经有现成的文章描述了该详细内容，如果有，请插入它的链接而不是再三重复内容。
- 如果上游的现有文档十分完善且维护程度良好，请只写 Arch 应特有的内容，并再提供到前者文档的链接。
- 不要在同一语言的链接中用 wiki 间链接，它们无法在 Special:WhatLinksHere 页面正确显示。例如在简体中文页面中不应该使用 `[[:zh-CN:Main Page]]`，而应该使用 `[[Main Page (简体中文)]]`。
  在不同语言间则应该使用后者这样的链接，因为这样将他们移动到外部站点时会更加简单。
  注意这些链接和#语言间链接是不同的，语言间链接前面没有冒号。

### 代码规范

- 添加命令或脚本时，请保持代码风格一致，也可以参考该程序语言的主流编码规范，并加以遵守。
- 避免使用过时的语言功能和风格，例如推荐使用 `$()` 做脚本命令，而不是````.

### 支持的内核版本

- Arch Wiki 支持的最老内核版本为 linux-lts 和 安装介质中的内核版本。
- 仅可以删除比两个版本更老的内核说明或适配信息。

### "提示与技巧" 段落

- 高级技巧或使用软件的示例
- 标准标题应是 提示与技巧
- 用子段落分别介绍不同的技巧

### "问题解决" 段落

- 软件常见问题的解决办法(与 #"已知问题" 段落 不同)。
- 标准标题是 问题解决。
- 可以提供绕过已知 bug 的临时解决方法，但是请务必提供该 bug 的链接地址；如果还未得到报告，请自行报告 bug，这样可以让它更容易被修复。
  增加 bug 链接对读者和编辑有如下好处：
  - 对读者来说，阅读该 Wiki 并非就到此为止了：他们还可以进一步访问链接，获取更多信息。
  - 对 Wiki 编辑来说，更好判断 bug 是否已经解决，容易维护；如果读者有得到新信息，他们也可以自主编辑。

### "已知问题" 段落

- 已知的 bug 或者使用问题，暂时还没有解决方法(与#"问题解决" 段落相反)。
- 标准标题是已知问题.
- 如果这个问题已经报告了 bug，请提供链接；如果没有报告，请报告它，这样会提高问题解决的概率。

### "参见" 段落

- 列出参考文档和额外信息.
- 应该是个列表，每行都以 `*` 开头。
- 一般使用 "参见" 作为标题，应该避免使用"外部链接","更多资源",“参阅” 等。

### 不相关内容

- 请不要署名，甚至把文章归功于自己：ArchWiki 是社区全体的劳动成果，文章的历史已能足够说明个人贡献。
  直接在 wiki 之外的地方专门撰文、并提供链接也不失为著名的好办法，可以通过 "参见" 段落实现。
- 一般用户没有上传文件的权限，而且不能用图片。作为替代，可以靠外部链接或者用 ASCII 编辑器，如Asciiflow 等绘制简单图形。原因：
  - 维护性: Arch 是滚动更新的，图片会大幅度地提高维护文章的难度。
  - 必要性: Arch 之道注定了它并不会开发或维护 GUI，所以没有显示图片的必要。
  - 资源性: 允许自行上传图片，会需要更多的精力来删除重复和不合适的图片。
  - 可行性: 有一些用户的网速很慢，纯文字页面不光能其加快访问速度
  - 效率性: 图片会剧烈消耗服务器的带宽和存储空间。
  - 简约性: 且界面简约美观。

### 措辞

- 文章的措辞应做到十分正式、专业且精确。
- 编写时，请注意不光说怎么样，还要回答为什么？ 解释远胜单纯的指导。
- 尽量避免不必要的缩写词。
- 不要加入个人评论，后者应该放到讨论页面，一般不要用第一人称。

## 分类页面

- 除了根分类外，每个分类都应该有一个父分类。
  根分类是 Category:DeveloperWiki, Category:Languages 和 Category:Sandbox.
- 分类可以属于多个父分类，只要父分类之间是平级的。
- 避免循环关系: 两个分类不能互相包含。
- 分类必须放到在分类页面的顶部。
- 分类不能被重定向。

## 重定向页面

- 重定向页面应该只包含重定向链接，除此之外一无所有。
- 只重定向到 Wiki 内部的页面，不要重定向到外部页面。

## 用户页面

- 用户页面不能被分类(除非极个别管理员允许的特例)。
- 用户名称空间中的文章只能链接字用户或者讨论名称空间，除非管理员明确同意。

## 一般规则

### 编辑摘要

请阅读Wiki 贡献的基本原则.

### HTML 标签

- 尽量不要使用 HTML 标签：尽量使用 wiki 标记和模板，参见 Help:Editing (简体中文)。
- 使用 `<pre>code</pre>` 的地方都改成 `{{bc|code}}`。使用 `<tt>text</tt>` 或 `<code>text</code>` 的地方，都改用 `{{ic|text}}`。
- 特别是避免 HTML 注释(`<!-- comment -->`): 一般使用 HTML 注释的文字都可以放到讨论页面。
  可以加入适当的 Help:Template#Article_status_templates。
- 仅在必要时才使用 `<br>`：要开启新段落时，用后面的空行实现。
  一个例外是作为一个列表的子项目时，或者在一个模板当中，这时必须使用`<br>`换行。

## 中英文混排

注意: 该原则自然只适用于 Arch Linux wiki 的 Chinese 条目

- 英文和数字使用半角字符
- 中文文字之间不加空格
- 中文文字与英文、阿拉伯数字及 @ # $ % ^ & * . ( ) 等符号之间加空格
- 中文标点之间不加空格
- 中文标点与前后字符（无论全角或半角）之间不加空格
- 如果括号内有中文，则使用中文括号，如果括号中的内容全部都是英文，则使用半角英文括号
- 当半角符号 / 表示“或者”之意时，与前后的字符之间均不加空格

Category:

- Help (简体中文)