Help:风格
(重定向自Help:Style)
这些风格约定鼓励简约、有条理和视觉一致的文章。请在编辑 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、文章状态、概览和简介
- 主体: 介绍、安装、配置、技巧、问题解决和更多内容
- 文章各部分的排列顺序应该为:
特殊字段[编辑 | 编辑源代码]
分类[编辑 | 编辑源代码]
- 每个文章至少应该属于一个分类。
- 一个文章可以属于多个分类,只要分类间没有包含关系。
- 分类必须放在文章的顶部,且在特殊字段之后。
注意: 这点和其它 MediaWiki 项目有时会不一样,后者经常把分类放在文章末尾。
- 分类与正文第一段(包括跨语言链接)之间不要插入空格,否则会有多余的空白。
- 参见文章分类。
提示:
- 由于分类页面中,MediaWiki会把相同首字母的页面归到一栏中,对于中文标题的页面,会把每个起始汉字归到一类,导致页面很混乱。因此在为名称由中文起始的页面,添加分类时请同时添加汉语拼音的首字母,如官方安装指南可以添加如下分类:
[[Category:简体中文|G]]
,这样该页面就会归类到字母G一栏的最上方。 - 不要添加多个字母(如:
[[Category:简体中文|GFAZZN]]
),否则会出现分类中中英文页面顺序混排的现象,使页面不便于查找。
跨语言链接[编辑 | 编辑源代码]
- 如果文章有其他语言的翻译,必须在分类和正文第一段之间加上這些跨语言链接。它们将显示在页面的左边。
- 跨语言链接和正文第一段之间不应该有空格,否则文章顶部会有多余的空白。
- 除了在当前页面上添加其它跨语言链接,您还需要在其它语言的页面上添加当前页面的跨语言链接。
- 每个语言的跨语言链接应只能有一个。
- 不要加入当前语言的跨语言链接。
- 跨语言链接需要根据其语言标签,來按字母表顺序排列,不要按语言本身的正式名稱顺序排列。例如,
就该排在
前面,哪怕 “Suomi” 就本来在 “Français” 之后。
- 参见 Help:i18n 和 Wikipedia:Help:Interlanguage links.
文章状态模板[编辑 | 编辑源代码]
- 文章状态模板应放在分类(或跨语言链接)和相关文章之间。
- 针对段落的标记,位置尽量靠近有问题的地方。
- 每个状态模板都应该包含简要的说明。有必要时,可以在讨论页面加以讨论。
相关文章[编辑 | 编辑源代码]
- 给出相关的文章列表
- 放在分类、跨语言链接和文章状态模板之后。
- 通过组合模板模板:相关文章开始, Template:Related 和模板:相关文章结束实现。详情参阅这几个模板的页面。
- 可以使用 Template:Related2 给出需要显示的标题翻译.
- 如果文章较多,或者需要详细描述,请使用参阅段落。
前言或介绍[编辑 | 编辑源代码]
- 描述文章的话题。
不要自己给软件下评论,一般可以访问项目主页,使用作者自己的描述。MediaTomb 是一个范例。 - 放在第一段前面
- 不要另外加上
==Introduction==
或==Preface==
说明:直接在第一段开始时写入即可。如果文章有足够多的段落,在前言和第一段直接会自动加入目录。 - 参见 Writing Article Introductions。
标准段落[编辑 | 编辑源代码]
"安装" 段落[编辑 | 编辑源代码]
- 安装段落介绍软件的安装方法,请参考 #指南.
- 标准的标题是安装,尽量往前放.
"已知问题" 段落[编辑 | 编辑源代码]
- 已知的 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.
表格[编辑 | 编辑源代码]
关于表格的语法,请参见 MediaWiki 帮助文档。
- 表格通常需要包含
wikitable
类。 - 对照表还应包含
sortable
类。 - 在适当的地方使用表格标题和表格模板。
表格标题的第一个字母应该大写,其余应该小写。(汉字并无大小写之分,故本条可被忽略)- 表格说明应使用定义列表,并放在表格之前。
指南[编辑 | 编辑源代码]
- 除非必要,请不要特别指定某编辑器(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}}
.
非官方软件仓库[编辑 | 编辑源代码]
- 要使用非官方软件仓库时,请先将其加入非官方软件仓库,然后提供一个链接,示例:
从[[Unofficial user repositories#example|示例]]
软件仓库安装 packageAUR.
不要在文章内直接给出启用软件仓库的详细信息。 - 必须链接到非官方软件仓库,而且请尽量使用段落链接:
[[Unofficial User Repositories#example|example]]
.
Systemd 单元操作[编辑 | 编辑源代码]
- 不要用systemctl 命令直接进行 start、 restart 或 stop 的操作。正确的说明方法应该是列出需要的单元,以及它们的依赖、冲突关系,描述所要执行的操作。例如:
- 要在开机时启动 GDM,请启用
gdm.service
.
- 要在开机时启动 GDM,请启用
- 如果模板需要实例化:
- 要在无线时自动切换 netctl 配置,启用一个带接口名称的
netctl-auto@.service
实例,例如netctl-auto@wlan0.service
.
- 要在无线时自动切换 netctl 配置,启用一个带接口名称的
- 可以根据上下文调整语句,但是请确保有到 systemd#Using units 文章段落的链接,可以直接引用或通过重定向实现,例如
[[start]]
,[[enable]]
or[[stop]]
.
Shells[编辑 | 编辑源代码]
- 除非必要,不要特别指定用户所用的 shell:撰写文章内容时请尽量做到与所用 shell 无关。
超链接[编辑 | 编辑源代码]
- 尽可能在该页面和相关页面插入彼此的超链接,实现 wiki 脉络性最大化。
- 像系统调用之类的文章 ArchWiki 却没有,大可直接用到维基百科页面的链接(使用
zhwp:
链接前缀)。 - 链接到 wiki 中其它页面时,不要用完整地址,而是用 wiki 间链接语法:
[[Wiki Article]]
。 wiki 引擎可以跟踪 wiki 间链接,好让大家更容易维护。
更多 wiki 间链接内容参见 Help:编辑#链接。- 链接到本页面段落时,不要隐藏井号,除了简化额外的格式,井号还明确告诉读者这是一个到本页面的链接。
- 请避免使用隐含链接,例如应该使用「参阅 systemd」而不是「参阅 here」。
- 仅在文件存在时才创建链接,不要链接到不存在的文件。
- 除极个别情况外,页面不能是死亡页面(没有任何到其它页面的链接)或孤立页面(没有其它文章链接到它).
- 添加内容时,首先请注意是不是已经有现成的文章描述了该详细内容,如果有,请插入它的链接而不是再三重复内容。
- 如果上游的现有文档十分完善且维护程度良好,请只写 Arch 应特有的内容,并提供到前者文档的链接。
- 如果某页面中文维基没有,请使用
{{link-en}}
模板来链接到英文 ArchWiki,以便在中文页面被创建时自动链接到中文页面。 - 需要链接到英文 ArchWiki 的时候,请使用链接前缀
arch:
。
手册页面[编辑 | 编辑源代码]
- 请用 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
.
支持的内核版本[编辑 | 编辑源代码]
不相关内容[编辑 | 编辑源代码]
- 请不要署名,甚至把文章归功于自己: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:编辑。
- 使用
<pre>code</pre>
的地方都改成{{bc|code}}
。使用<tt>text</tt>
或<code>text</code>
的地方,都改用{{ic|text}}
。 - 特别是避免 HTML 注释(
<!-- comment -->
): 一般使用 HTML 注释的文字都可以放到讨论页面。
可以加入适当的 Help:Template#Article status templates。 - 仅在必要时才使用
<br>
:要开启新段落时,用后面的空行实现。
一个例外是作为一个列表的子项目时,或者在一个模板当中,这时必须使用<br>
换行。 - 大段代码可考虑使用 <syntaxhighlight> 标签进行语法高亮
中文排版[编辑 | 编辑源代码]
- 中文之间不要加空格(即使样式不同,比如包含链接)
- 尽量避免中文斜体
中英文混排[编辑 | 编辑源代码]
- 英文和数字使用半角字符
- 中文文字之间不加空格
- 中文文字与英文、阿拉伯数字及 @ # $ % ^ & * . ( ) 等符号之间加空格
- 中文标点之间不加空格
- 中文标点与前后字符(无论全角或半角)之间不加空格
- 翻译时,正文的英文常见标点等需要换为中文标点
- 当半角符号 / 表示“或者”之意时,与前后的字符之间均不加空格
术语[编辑 | 编辑源代码]
为保持一致的翻译风格,在翻译时请遵守以下规范:
- 在正式的规范完成前,请暂时先按照现有的风格翻译。
相关讨论: