Difference between revisions of "Help:Style (简体中文)"

From ArchWiki
Jump to: navigation, search
(增添中英文混排指导章节)
(Category:Template is going to be deleted)
Line 61: Line 61:
  
 
===文章状态模板===
 
===文章状态模板===
*[[:Category:Template#Article_status_templates|文章状态模板]] 应放在分类(或语言间链接)和文章摘要之间。
+
*[[Help:Template#Article_status_templates|文章状态模板]] 应放在分类(或语言间链接)和文章摘要之间。
 
*文章的某段落也可以使用文章状态模板。
 
*文章的某段落也可以使用文章状态模板。
 
*每个状态模版都应该包含简要的说明。有必要时,可以在讨论页面加以讨论。
 
*每个状态模版都应该包含简要的说明。有必要时,可以在讨论页面加以讨论。
Line 234: Line 234:
  
 
==分类页面==
 
==分类页面==
*除了根分类外,每个分类都应该有一个父分类。<br>根分类是 [[:Category:DeveloperWiki]],  [[:Category:Languages]], [[:Category:Sandbox]] 和 [[:Category:Template]].
+
*除了根分类外,每个分类都应该有一个父分类。<br>根分类是 [[:Category:DeveloperWiki]],  [[:Category:Languages]] [[:Category:Sandbox]].
 
*分类可以属于多个父分类,只要父分类之间是平级的。
 
*分类可以属于多个父分类,只要父分类之间是平级的。
 
*避免循环关系: 两个分类不能互相包含。
 
*避免循环关系: 两个分类不能互相包含。
Line 262: Line 262:
 
*尽量不要使用 HTML 标签:尽量使用 wiki 标记和模板,参见 [[Help:Editing (简体中文)]]。
 
*尽量不要使用 HTML 标签:尽量使用 wiki 标记和模板,参见 [[Help:Editing (简体中文)]]。
 
*使用 {{ic|<nowiki><pre>code</pre></nowiki>}} 的地方都改成 {{ic|<nowiki>{{bc|code}}</nowiki>}}。使用 {{ic|<nowiki><tt>text</tt></nowiki>}} 或 {{ic|<nowiki><code>text</code></nowiki>}} 的地方,都改用 {{ic|<nowiki>{{ic|text}}</nowiki>}}。
 
*使用 {{ic|<nowiki><pre>code</pre></nowiki>}} 的地方都改成 {{ic|<nowiki>{{bc|code}}</nowiki>}}。使用 {{ic|<nowiki><tt>text</tt></nowiki>}} 或 {{ic|<nowiki><code>text</code></nowiki>}} 的地方,都改用 {{ic|<nowiki>{{ic|text}}</nowiki>}}。
*特别是避免 HTML 注释({{ic|<nowiki><!-- comment --></nowiki>}}): 一般使用 HTML 注释的文字都可以放到讨论页面。 <br> 可以加入适当的 [[:Category:Template#Article_status_templates]]。
+
*特别是避免 HTML 注释({{ic|<nowiki><!-- comment --></nowiki>}}): 一般使用 HTML 注释的文字都可以放到讨论页面。 <br> 可以加入适当的 [[Help:Template#Article_status_templates]]。
 
*仅在必要时才使用 {{ic|<nowiki><br></nowiki>}}:要开启新段落时,用后面的空行实现。<br> 一个例外是作为一个列表的子项目时,或者在一个模板当中,这时必须使用{{ic|<nowiki><br></nowiki>}}换行。
 
*仅在必要时才使用 {{ic|<nowiki><br></nowiki>}}:要开启新段落时,用后面的空行实现。<br> 一个例外是作为一个列表的子项目时,或者在一个模板当中,这时必须使用{{ic|<nowiki><br></nowiki>}}换行。
  

Revision as of 09:18, 17 November 2013

Template:Article summary start Template:Article summary text Template:Article summary heading Template:Article summary wiki Template:Article summary wiki Template:Article summary wiki Template:Article summary end

翻译状态: 本文是英文页面 Help:Style翻译,最后翻译时间:2013-08-28,点击这里可以查看翻译后英文页面的改动。

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

文章页面

标题

  • 使用全名而不是缩写。如果您认为它们都很常见,可创建一个从缩写到全名的重定向 。不要用括号包含缩写。
  • 参见 文章命名指导

布局

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:i18nWikipedia:Help:Interlanguage links.

文章状态模板

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

摘要

  • 描述文章的结构、所包含的内容
  • 放在分类、语言间链接和文章状态模板之后。
  • 参见 Writing Article Overviews

前言或介绍

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

段落标题

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

空行

代码格式模板

  • 使用 {{ic|code}} 格式化要嵌入的微代码、文件名、命令名、变量名等。例如:
    在终端运行sh ./hello_world.sh
  • 使用 {{bc|code}} 格式化当行或多行代码(命令行的输入或输出内容、文件内容) 例如:
$ sh ./hello_world.sh
Hello World
#!/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"

命令行文字

  • 使用 $ 作为一般用户权限命令的提示符;使用 # 作为 root 命令的提示符。
    注意: 因为 # 也经常表示文本文件中的注释符号,所以经常要澄清是运行命令还是编辑文件,以避免不必要的误解。
  • 引入命令的句子尽量以 : 结尾。
  • 建议使用 # command 而不是 $ sudo command
  • 尽量少假设用户会使用 sudo 或其它权限获取工具(例如 gksukdesu)。
  • 应该避免# 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+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

软件包管理

官方软件包

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

AUR 软件包

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

内核模块操作

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

守护进程操作

  • 举例说明 startrestartstop 守护进程的方法同样已过时,正确的说明方法应该是列出需要的守护进程,以及它们的依赖、冲突关系,加以描述所要执行的行为,最后再补充上 Daemon (简体中文) 的超链接。
  • 新手指南 及其子页面同样毋须遵守该规范.

注意, 警告, 技巧

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

Shells

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

超链接

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

代码规范

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

"提示与技巧" 段落

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

"问题解决" 段落

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

"已知问题" 段落

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

"参见" 段落

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

不相关内容

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

措辞

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

讨论页面

  • 在讨论页面尾部增加一个新话题并提供合适的标题。也可以使用讨论页面顶部的 + 标签。
  • 用冒号缩进每个回答。
  • 不要编辑别人已经回复的讨论,否则严重打乱讨论秩序。最多只允许添加删除线(使用<s> tags) 而且必须提供相应的解释。
  • 所有编辑都加上签名(~~~~).
  • 讨论页面不应该有分类。
  • 如果话题结束了,可以给讨论内容加上删除线 <s> 标记。
    结束的话题过一段时间后应该删除。
  • 参见 Help:Editing (简体中文)#讨论页面.

分类页面

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

重定向页面

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

模板页面

用户页面

  • 用户页面不能被分类(除非极个别管理员允许的特例)。

一般规则

编辑摘要

  • 一些专职人员和志愿者每天都会检查所有的修改,你应该帮助他们,给每个修改添加摘要。
    • 如果编辑是 小改动,例如语法或词句的修改,请标记为小改动并简单描述。
    • 如果进行大改动,例如添加、移动、删除或修改内容,除了提供摘要外,应该解释修改的原因,如果有相关的 wiki 页面或论坛帖子,请提供链接。
    • 讨论页面中加入内容并不需要解释,因为原因很明显
      而删除讨论时,应该提供一些说明(例如"closed discussion," "fixed,"等.) 同时给出讨论的标题以方便历史查询和重新打开。
小贴士: 查看 最近更改 中的摘要可以学习其他人是如何做的,但是请注意并不是所有人都遵循这些准则。
  • 执行大的改动时,最好将其分到多个编辑操作中,根据逻辑步骤一步一步完成。
    特别是在文章中或文章之间移动段落时,应该避免在同一个编辑中进行内容修改,否则很难查看修改的具体内容。

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