Help:风格

来自 Arch Linux 中文维基
(重定向自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、文章状态、概览和简介
  • 主体: 介绍、安装、配置、技巧、问题解决和更多内容
  • 文章各部分的排列顺序应该为:
  1. #特殊字段 (可选)
  2. #分类
  3. #跨语言链接 (可选)
  4. #文章状态模板 (可选)
  5. #相关文章 (可选)
  6. #前言或介绍
  7. 目录 (自动生成)
  8. 文章特有的部分

特殊字段[编辑 | 编辑源代码]

  • 特殊字段会修改文章的显示方式,但并不会添加内容。这些字段应该位于文章的最开始,尤其是这两个:{{DISPLAYTITLE:title}}模板:小写标题

分类[编辑 | 编辑源代码]

  • 每个文章至少应该属于一个分类。
  • 一个文章可以属于多个分类,只要分类间没有包含关系。
  • 分类必须放在文章的顶部,且在特殊字段之后。
注意: 这点和其它 MediaWiki 项目有时会不一样,后者经常把分类放在文章末尾。
  • 分类与正文第一段(包括跨语言链接)之间不要插入空格,否则会有多余的空白。
  • 参见 文章分类
提示:
  • 由于分类页面中,MediaWiki会把相同首字母的页面归到一栏中,对于中文标题的页面,会把每个起始汉字归到一类,导致页面很混乱。因此在为名称由中文起始的页面,添加分类时请同时添加汉语拼音的首字母,如官方安装指南可以添加如下分类:[[Category:简体中文|G]],这样该页面就会归类到字母G一栏的最上方。
  • 不要添加多个字母(如:[[Category:简体中文|GFAZZN]]),否则会出现分类中中英文页面顺序混排的现象,使页面不便于查找。

跨语言链接[编辑 | 编辑源代码]

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

文章状态模板[编辑 | 编辑源代码]

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

相关文章[编辑 | 编辑源代码]

前言或介绍[编辑 | 编辑源代码]

  • 描述文章的话题。
    不要自己给软件下评论,一般可以访问项目主页,使用作者自己的描述。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 或其它权限获取工具(例如 gksukdesu)。
  • 应该避免# sudo command,唯一的例外是用sudo-u选项修改用户,这时提示符可以与其它命令一致,默认使用$
  • 不要在一行命令的代码框里添加注释,例如# pacman -S foo #Install package foo就不好
  • 代码行不要过长,请尽量换行。

键盘按键[编辑 | 编辑源代码]

  • 表示按键的标准方法是使用 Template:ic 模板。
  • 字母键应该小写:a. 大写字母用 Shift+a,不要使用 Shift+AA
  • 表示按键组合的正确方法是使用 + 号连接,不要增加额外空格,在一个模板中包含多个按键:Ctrl+c.
    下面格式都应该避免使用:Ctrl + c, Ctrl+c, Ctrl-c
  • 特殊键的标准名称:
    • Shift (不要用 SHIFT)
    • Ctrl (不要用 CTRLControl)
    • Alt (不要用 ALT)
    • Super (不要用 WindowsMod)
    • Enter (不要用 ENTERReturn)
    • Esc (不要用 ESCEscape)
    • Space (不要用 SPACE)
    • Backspace
    • Tab
    • Ins (不要用 INSInsert)
    • Del (不要用 DELDelete)
    • Print Screen
    • Up (不要使用 Up Arrow) – 其它方向键类似
    • PageUp
    • PageDown
    • Fn (不要使用 FNfn) – 不同笔记本上的功能按键请参考 这里

注意, 警告, 技巧[编辑 | 编辑源代码]

  • 注意 应该用在用户预料不到的地方。包括与文章关系不大的细节知识、软件包名称变动等。
    也可以用来强调容易被用户忽略的地方。
  • 警告 用来指出需要特别警惕的地方,比如不可逆转的修改、损害系统的可能性等。警告应该直接指出最坏的情况,并给出相应措施。不要滥用警告,如果不确定的时候,用注意即可。
  • 提示 用来给出一个可能会相当有用的小技巧,一般不是必须的,省略也无妨。
  • 如果多个注意、警告、技巧连用,最好组合到单一模板中,除非彼此毫无相干。例如:
提示:
  • 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 packagepacman -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 命令直接进行 startrestartstop 的操作。正确的说明方法应该是列出需要的单元,以及它们的依赖、冲突关系,描述所要执行的操作。例如:
要在开机时启动 GDM,请 启用 gdm.service.
如果模板需要实例化:
要在无线时自动切换 netctl 配置,启用 一个带接口名称的 netctl-auto@.service 实例,例如 netctl-auto@wlan0.service.
可以根据上下文调整语句,但是请确保有到 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:

手册页面[编辑 | 编辑源代码]

代码规范[编辑 | 编辑源代码]

  • 添加命令或脚本时,请保持代码风格一致,也可以参考该程序语言的主流编码规范,并加以遵守。
  • 避免使用过时的语言功能和风格,例如推荐使用 $() 做脚本命令,而不是``.
  • 脚本尽可能短,只需表达需要的信息。尽量使用 伪变量 而不是真实变量。不要添加参数解析或输出等无关功能。
  • 代码应该在文本解释不太清楚的时候使用,如果脚本确实有用但是不是必须,可以考虑使用 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,所以没有显示图片的必要。
    • 资源性: 允许自行上传图片,会需要更多的精力来删除重复和不合适的图片。
    • 可行性: 有一些用户的网速很慢,纯文字页面不光能加快其访问速度
    • 效率性: 图片会剧烈消耗服务器的带宽和存储空间。
    • 简约性: 且界面简约美观。

拼写[编辑 | 编辑源代码]

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

措辞[编辑 | 编辑源代码]

  • 文章的措辞应做到十分正式、专业且精确。
  • 编写时,请注意不光说怎么样,还要回答为什么? 解释远胜单纯的指导。
  • 不要加入个人评论,后者应该放到讨论页面,一般不要用第一人称。
  • 不要说现在,当前等等,请给出具体的时间。
  • 编辑内容时,保持和页面其它内容的一致性,用一样的人称描述。
  • 在多个选项间提供选择时,不要感性的建议一个或另一个,请可观的描述每一个选择的优点和缺点,让用户自行选择。
  • 翻译页面时,请尽量避免使用第二人称代词“你”或“您”。确实需要使用第二人称代词时,如果页面中现存的翻译已使用其中的一种,请与其保持一致,如果使用了多种,请考虑统一为其中的一种;如果页面中没有使用,则可以自行决定使用哪一种,但请确保在翻译中保持一致。

分类页面[编辑 | 编辑源代码]

重定向页面[编辑 | 编辑源代码]

  • 建议创建缩写词到正式文章的重定向,比如创建 ALSA, daemonAIGLX. 重定向可以简化链接: [[Advanced Linux Sound Architecture|ALSA]], [[daemons|daemon]][[Xorg#Composite|AIGLX]].
  • 重定向页面应该只包含重定向链接,除此之外一无所有。除非:
  • 只重定向到 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> 标签进行语法高亮

中文排版[编辑 | 编辑源代码]

  • 中文之间不要加空格(即使样式不同,比如包含链接)
  • 尽量避免中文斜体

中英文混排[编辑 | 编辑源代码]

  • 英文和数字使用半角字符
  • 中文文字之间不加空格
  • 中文文字与英文、阿拉伯数字及 @ # $ % ^ & * . ( ) 等符号之间加空格
  • 中文标点之间不加空格
  • 中文标点与前后字符(无论全角或半角)之间不加空格
  • 翻译时,正文的英文常见标点等需要换为中文标点
  • 当半角符号 / 表示“或者”之意时,与前后的字符之间均不加空格

术语[编辑 | 编辑源代码]

这篇文章的某些内容需要扩充。

原因: 需要规范术语。 (在 Help talk:风格 中讨论)

为保持一致的翻译风格,在翻译时请遵守以下规范:

  • 在正式的规范完成前,请暂时先按照现有的风格翻译。

相关讨论: