Help:Style (简体中文)

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

翻译状态：本文是 Help:Style 的翻译。上次翻译日期：2021-09-14。如果英文版本有所更改，则您可以帮助同步翻译。

这些风格约定鼓励简约、有条理和视觉一致的文章。请在编辑 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 page/my subpage".
默认情况下文章使用英文的单数形式命名，如果文章代表一类问题，则使用复数形式。
尽量使用全名而不是缩写。如果您认为它们都很常见，可创建一个从缩写到全名的重定向。不要用括号包含缩写。
本地化页面也应该遵循 Help:i18n#Page titles.
参见文章命名指导。

布局

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

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

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

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

特殊字段

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

分类

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

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

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

提示：

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

语言间链接

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

文章状态模板

文章状态模板应放在分类(或语言间链接)和相关文章之间。
针对段落的标记，位置尽量靠近有问题的地方。
每个状态模版都应该包含简要的说明。有必要时，可以在讨论页面加以讨论。

前言或介绍

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

标准段落

"安装" 段落

安装段落介绍软件的安装方法，请参考 #Package management instructions^{[损坏的链接：无效的章节]}.
标准的标题是安装，尽量往前放.

"已知问题" 段落

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

"提示与技巧" 段落

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

"问题解决" 段落

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

"参见" 段落

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

段落标题

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

格式

代码格式

使用 Template:ic 格式化要嵌入的代码片段、文件名、路径、命令名、配置参数、变量等。例如:
在终端运行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就不好
代码行不要过长，请尽量换行。

键盘按键

表示按键的标准方法是使用 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
- Up (不要使用 ↑ 或 Up Arrow) – 其它方向键类似
- PageUp
- PageDown
- Fn (不要使用 FN 或 fn) – 不同笔记本上的功能按键请参考这里。

注意, 警告, 技巧

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

提示：

Tip example #1.
Tip example #2.

Tables

See mw:Help:Tables for the syntax.

Tables should generally have the wikitable class.
Comparison tables should additionally have the sortable class.
Use table headers and table cell templates when appropriate.
Table headers should be in sentence case.
Table legends should use definition lists and be placed before tables.

指南

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

将下行附加到 ~/.bash_logout:

clear
reset

合适的话可以增加一个到 Help:Reading#Append, add, create, edit 的链接。

官方软件包

在示意要从官方软件仓库安装软件包时，请避免直接标出 pacman 命令。不仅简化内容(每个 Arch 用户都应该知道如何使用 pacman)而且避免了 pacman -Sy package 之类的键误，以及 pacman -S package 和 pacman -Syu package 孰好孰坏的无谓争论。同理，也不要引入 pacman 前端或图形界面等。
相反，请像这样简单地示范：安装说明应该使用： [[pacman (简体中文)|安装]] 软件包 {{Pkg|package}}。
如果安装的是一组软件包，则使用 : 安装软件组 foobar.
必须要用 Template:Pkg/和Template:Grp 模板进行格式化，例如{{Pkg|package}}.
不要特意指出软件包是在 [core]、[extra] 或 [community] 中的哪一个仓库，因为一个软件包可能会在不同仓库之间转移。此外如果软件包位于 [multilib] 仓库，请这样示范：
安装官方软件仓库的 package 时，需要事先开启 multilib 仓库。

AUR 软件包

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

非官方软件仓库

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

Systemd 单元操作

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

要在开机时启动 GDM，请启用 gdm.service.

如果模板需要实例化：

要在无线时自动切换 netctl 配置，启用一个带接口名称的 netctl-auto@.service 实例，例如 netctl-auto@wlan0.service.

可以根据上下文调整语句，但是请确保有到 systemd#Using units 文章段落的链接，可以直接引用或通过重定向实现，例如 [[start]], [[enable]] or [[stop]].

Shells

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

超链接

参考 Help:Editing#Links。

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

手册页面

请用 Template:man 引用手册页面。

代码规范

添加命令或脚本时，请保持代码风格一致，也可以参考该程序语言的主流编码规范，并加以遵守。
避免使用过时的语言功能和风格，例如推荐使用 $() 做脚本命令，而不是``.
脚本尽可能短，只需表达需要的信息。尽量使用伪变量而不是真实变量。不要添加参数解析或输出等无关功能。
代码应该在文本解释不太清楚的时候使用，如果脚本确实有用但是不是必须，可以考虑使用 gist 引用。
明确标明是文件还是目录/文件夹，比如

"检查目录 /sys/firmware/efi 是否已被创建",不要写 "检查 /sys/firmware/efi 是否已被创建".
"将 .conf 文件放入 /etc/modules-load.d/"，而不是 "将 .conf 文件放入 /etc/modules-load.d".

包含空格的参数应该用引号引用，使用 cd "foo bar" 而不是 cd foo\ bar.

支持的内核版本

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

不相关内容

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

拼写

尽量避免不必要的缩写词。
专有名词拼写与项目官方主页里面的拼写保持一致。

措辞

文章的措辞应做到十分正式、专业且精确。
编写时，请注意不光说怎么样，还要回答为什么？ 解释远胜单纯的指导。
不要加入个人评论，后者应该放到讨论页面，一般不要用第一人称。
不要说现在，当前等等，请给出具体的时间。
编辑内容时，保持和页面其它内容的一致性，用一样的人称描述。
在多个选项间提供选择时，不要感性的建议一个或另一个，请可观的描述每一个选择的优点和缺点，让用户自行选择。

分类页面

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

重定向页面

建议创建缩写词到正式文章的重定向，比如创建 ALSA, daemon 或 AIGLX. 重定向可以简化链接： [[Advanced Linux Sound Architecture|ALSA]], [[daemons|daemon]] 或 [[Xorg#Composite|AIGLX]].
重定向页面应该只包含重定向链接，除此之外一无所有。除非：
- 是归档页面，虽然是重定向，需要属于分类 Category:Archive.
- 是重命名分类可以包含一个 Template:Archive 标记.
只重定向到 Wiki 内部的页面，不要重定向到外部页面。
参考 Help:Editing#Redirects

用户页面

用户这一名字空间中的页面不能被分类。
用户这一名字空间中的页面只能链接自“用户”或者“讨论”名字空间中的其他页面，除非管理员明确同意。

一般规则

编辑摘要

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

HTML 标签

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

中英文混排

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

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