Help:Style (简体中文)

From ArchWiki

相关文章

翻译状态：本文是 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、文章状态、概览和简介
  • 主体: 介绍、安装、配置、技巧、问题解决和更多内容
  • 文章各部分的排列顺序应该为:
  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.

文章状态模板

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

相关文章

前言或介绍

  • 描述文章的话题。
    不要自己给软件下评论，一般可以访问项目主页，使用作者自己的描述。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.

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}}.

非官方软件仓库

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

Systemd 单元操作

  • 不要用systemctl 命令直接进行 start、 restart 或 stop 的操作。正确的说明方法应该是列出需要的单元，以及它们的依赖、冲突关系，描述所要执行的操作。例如：
要在开机时启动 GDM，请 启用 gdm.service.
如果模板需要实例化：
要在无线时自动切换 netctl 配置，启用 一个带接口名称的 [email protected] 实例，例如 [email protected].
可以根据上下文调整语句，但是请确保有到 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 (简体中文)]]。
    在不同语言间则应该使用后者这样的链接，因为这样将他们移动到外部站点时会更加简单。
    注意这些链接和#语言间链接是不同的，语言间链接前面没有冒号。

手册页面

代码规范

  • 添加命令或脚本时，请保持代码风格一致，也可以参考该程序语言的主流编码规范，并加以遵守。
  • 避免使用过时的语言功能和风格，例如推荐使用 $() 做脚本命令，而不是``.
  • 脚本尽可能短，只需表达需要的信息。尽量使用 伪变量 而不是真实变量。不要添加参数解析或输出等无关功能。
  • 代码应该在文本解释不太清楚的时候使用，如果脚本确实有用但是不是必须，可以考虑使用 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, daemon 或 AIGLX. 重定向可以简化链接： [[Advanced Linux Sound Architecture|ALSA]], [[daemons|daemon]] 或 [[Xorg#Composite|AIGLX]].
  • 重定向页面应该只包含重定向链接，除此之外一无所有。除非：
  • 只重定向到 Wiki 内部的页面，不要重定向到外部页面。
  • 参考 Help:Editing#Redirects

用户页面

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

一般规则

编辑摘要

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