User:Junkie/Help:Editing

From FedoraProject

Jump to: navigation, search
Important.png
2008-09-06 Wiki 结构页面位置
Help:Wiki_structure 描述了本wiki的结构, 包括了页面的命名.
Note.png
标记语言的其它资源
Help:Editing from Mediawiki.org 是一个不错的标记语言帮助. 这有一张方便的 reference card 图片.
Idea.png
旧的 wiki 内容也会有帮助
旧的 wiki 和内容快照在 http://fedoraproject.org/wikiold/.
Idea.png
Wiki 迁移需要做的事
阅读 FedoraProject:Wiki migration to-do 后决定是否你需要为你的用户或 SIG/subProject 页面做些什么.

Fedora Project Wiki 对编辑来说入门是很容易的, 刚开始使用 wiki 需花点时间, 你应该看看我们准备的一些准则. 本页的内容提供了这些准则和技巧来帮助你.


这个文档分为3部分: 获得编辑权限, wiki 基本编辑, 高级编辑.

Contents

获得编辑权限

为了防止不怀好意的人破坏 Fedora Project Wiki, 我们不得不对编辑权限做限制. 要获得 wiki 的编辑权限, 你必须完成下面的步骤. 任何人都可以获得编辑权限

  1. 熟悉本页信息及本页链接到的页面信息. wiki 所遵循的基本准则都在这里. 没有遵循这些准则造成不必要的工作, 其他志愿者可能撤销你的编辑特权。
  2. 通过 Fedora Account System 完成贡献者许可协议. 签署 CLA, Fedora Project 根据 Open Publication License 1.0 给你 WiKi 贡献的许可执照. 这确保你的贡献就像 Fedora 发行版一样永远免费为社区使用, 修改和重新分配. 请参阅我们的 Legal 获取更多信息. 遵循 Infrastructure/AccountSystem/CLAHowTo 的指示.
Note.png
如果你对网站维护感兴趣, 或者希望成为 Fedora Websites team 的一员, 请看 Websites页面.
关于使用 wiki 编写新的正式 Fedora documentation的信息可以看 Writing Wiki Documentation.

准则和 Wiki 礼节

当修改 WiKi 时候有很简单的几点要遵循. 下面是一些例子. 通常要有礼貌和常识. 不顾这些准则引发的问题会导致你被取消编辑权限. 如果有问题, 可以在 #fedora-websites freenode 里询问.

介绍你自己

开始编写任何页面前, 恳请在你的 wiki 页面里介绍你的信息. 在 wiki 注册了你的名字后, 你自动拥有一个个人 wiki 页面, 这页是 http://fedoraproject.org/wiki/User:<username>, <username> 的地方替换为你 Fedora Account System 的帐号名. 你也可以很容易的进入你的 wiki 页通过点击任何 wiki 页面顶部右上角你名字的链接.

例如, 看看 wiki 页面贡献者.

至少提到你的邮件地址, 如果你经常在 IRC 上, 你的 IRC 昵称和频道也列出来.

总是关注你产生或编辑的页面

关注你产生或编辑的页面是非常重要的, 这样你就可以与他人在 WiKi 内容上协调的工作. WiKi 作者往往会给页面添加便条, 给其他一起协作的作者传递信息, 帮助追踪这些修改.

你登录后, 可以在页面顶部的标签栏看到 watch 链接.

设为粗体

编辑时在有变化的地方设置粗体. WiKi 变化是可追踪, 并且在必要时候可以恢复. 这并不意味着你应该轻率决策特别是当重要文档有很大改变的时候.

关于设为粗体的更多信息, 可以看看 be bold editing guideline on Wikipedia.

避免对法律问题页面不必要的修改

这些页面要小心编写, 用词也要精心挑选. 当改变这些文档时候, 最好在审查后再进行更改. 你可以联系 Fedora Advisory Board 得到帮助.

不要提供详细的禁止项目

不要添加任何违反国际法的内容. 记住 Fedora Project 的实体在美国并且被美国法律所管辖. 如果你认为你有例外, 把这个问题带到 Websites 小组来讨论. 应该避免在 ForbiddenItems 页面里的项目.

有问题到 Websites 小组来讨论, 如果需要, 他们能得到官方的说法.

编辑向导或页面要小心

大型并且重要的向导, 例如 Packaging Guidelines, 通常被特别的人或者小组所管理. 当你认为有必要改变时最好和他们一起协作.

重要的页面, 例如 FedoraMain 或者 Download 页面, 是很多游客访问最先访问的. 改变这些页面一般应交给经验丰富的贡献者. 如果你认为有这样一个网页应该被改变, 把这个问题 Websites 带到小组进行讨论.

不要编辑页面只为编辑页面

避免毫无意义的修改. 正在改建的页面只是把你的名字放在修改日志是不能接受的. 有很多网页(事实上其中大部分是)有真正的错误, 可以予以纠正. 不要做无谓的修改, 例如删除或添加空格或改变fedoraproject.org 链接到 www.fedoraproject.org(前者是首选), 尝试找出错误的拼写, 语法或标点符号, 可以予以纠正. 另外, 在纠正一个小错误后, 使用适当的复选框标记为 "This is a minor edit", 然后再保存它.

避免没有协调好就重命名或移动页面的内容

WiKi 页面通常被引用和链接了其他很多地方的页面. 重要的是, 在内容移动或重命名页面前配合好适当的团体. 没有强有力的理由最好避免这样做. 如果你想讨论移动具体的项目, 带你的问题到 Websites 小组来讨论.

删除页面

WiKi 页面不再需要了, 可以通过添加 {{Delete|Reason}} 到页面的开始来标记删除, 这样 WiKi 管理员能够确保重要的或者归档内容不丢失.

领会 Fedora 的思想很重要

例如, 努力保持桌面的中立性和用户友好, 特别是对于那些非技术人员的新 Linux 用户和新 Fedora 用户. 用户可能会使用 GNOME, KDE, console 或者其他环境. 当在页面里写指令的时候记住这一点, 确定 Fedora 的奉献精神, 使得自由和开放源码技术适合的表现出来.

对附件签名

当往 WiKi 页面附加文件时, 你应该用你的 GPG key 生成签名文件. 但一些文件格式, 例如 RPM 包, 它支持 GPG keys, 就不用生成签名文件了. 签名文件可以附加到页面原始附件的旁边, 或者包含在页面内容里.

有了GPG 签名, 别人下载你的文件就可以进行验证是否是你上传的, 保证中途没有被修改或文件损坏. 签名不会违反你的隐私, 它只是让其他人确认这是你的文件.

图片和简单文档没有进行签名也是安全的, 但是添加签名对验证你是作者没有坏处.

如果你还没有 GPG key 或者想知道更多, 看 Cryptography 页面.

审查更改防止错误

无论你是技术熟练的作家, 或者你的英语能力不强, 请别人来审查. 良好的书面文档对 Fedora 形象是重要的. 即使是最好的作家很容易拼写错误或其他错误, 花点时间审查变更以发现小错误. 当编辑页面时使用 Show preview 检查语法.

Fedora 是一个社区

当正在编辑内容时, 不管是 WiKi 或其它地方, 记住 Fedora 是一个社区. 我们是一体的统一的, 朝相同目标前进. 我们并不需要区分一个集团或反对别人的阶级. 例如, 没有必要区分那些为 redhat 工作的贡献者和其他贡献者. 所有贡献者都是同社区的组成部份. 在某些情况分类是必须的, 但是可以避免的除外.

如果你有不知道, 随时提问

其他社区成员将乐意为你提供帮助. freenode 的 #fedora-websites 频道是讨论 wiki 或其他 Fedora 站点的好地方.

关注你的页面, 其他人的页面

两个细节使得 WiKi 成功的作为一个开放的内容协作工具. 首先是能够关注你负责的页面, 使页面可以保持正确. 二是可以观看其它内容的发展, 成长, 有时需要你们的帮助.

要关注页面, 登录后, 点击 标题栏的 watch 链接, 完后它应当变成了 unwatch. 如果页面顶端显示unwatch, 表示页面已经处于关注状态. 点击unwatch 取消对页面的关注.

要在页面每一次修改后收到邮件, 进入 my preferences (页面顶端), 在User profile 标签, Email下, 选中适当的复选框.

使用 Special:Watchlist

Special:Watchlist (登录后点击页面顶部的my watchlist) 显示了当前你关注的页面. 更多信息关于如何使用这一页面, 阅读 Mediawiki.org 的 [1] 手册.

我们正在维护独立的 Watchlist_How-To, 帮助 Fedora 贡献者的具体建议和工具

概述变更 (又叫日志信息提交) -- 这是准则

我们能够对修改快速一览并且知道具体修改的内容. 全文差异并不是都可用的. 你必须提供一个修改概述(Summary: field when editing). 这类似于更新信息. 简述你为什么这么做以及其它有用的链接和细节.

如果您没有填入概述, 这应该是罕见的例外. 原因之一是做了细微修改. 在这种情况下, 请务必选中 This is a minor edit 后再保存.

编辑 Mediawiki

Note.png
如果你需要语法下面的帮助中没有列出, 在 Mediawiki Help 应该包含了.

基本语法

输入 显示
'''bold text'''
bold text
''italics''
italics
'''''bold italics'''''
bold italics
<code>Monospace text</code>
Monospace text

列表

输入 显示
* A list item
* Another list item
** Oh joy, more list items!
  • A list item
  • Another list item
    • Oh joy, more list items!
# A numbered item
# Another numbered item
## Sub items
## More sub items
# Third numbered item
  1. A numbered item
  2. Another numbered item
    1. Sub items
    2. More sub items
  3. Third numbered item
* An unordered item...
*# With a sub-list that is ordered
*# More steps
* Back to the first list
*# Another ordered list
*#* With its own sub point
  • An unordered item...
    1. With a sub-list that is ordered
    2. More steps
  • Back to the first list
    1. Another ordered list
      • With its own sub point

链接

输入 显示
Visit [[DocsProject]] to learn more about
Fedora's documentation.
Visit DocsProject to learn more about Fedora's documentation.
Our [[Websites|websites team]] offers many
individuals who can help Fedora.
Our websites team offers many individuals who can help Fedora.
See [[Artwork#Join]] on how to
join the Art Team.
See Artwork#Join on how to join the Art Team.
[[The weather in London]] is a
page that doesn't exist yet.
The weather in London is a page that doesn't exist yet.
http://fedoraproject.org/
http://fedoraproject.org/
Here are some sites:
[http://www.deviantart.com]
[http://www.flickr.com]
Here are some sites: [2] [3]
[http://fedoraproject.org Our home page]
is full of interesting information.
Our home page is full of interesting information.
Use a ':' in the link to link
to an [[:Image:Growth_wide.jpg|image]].
Use a ':' in the link to link to an image.
The [[:Category:Documentation]] lists all 
end-user documentation.
The Category:Documentation lists all end-user documentation.
The [[Category:Documentation]] link puts
this page in the listed category; the link
appears automatically on the bottom of the
page and not inline.
The [[Category:Documentation]] link puts this page in the listed category; the link appears automatically on the bottom of the page and not inline.
Note.png
有两种方法使用分类链接
当你链接到分类页面, 确保在分类单词的前面使用 ':'. 当页面是当前分类可以忽略':' . 参考上面的例子.

表格

表格应该在必要时候才使用.

表格的高级使用, 进一步阅读 Mediawiki.org's page on tables.

输入 显示
Start a table
{|
Table header
! Column 1 !! Column 2 !! Column 3
New row
|-
Table row
| Cell 1 || Cell 2 || Cell 3
End a table
|}

IRC 日志

IRC 日志 可以放在 <pre> 标签里, 或者使用 irclog2html and Ian's MediaWiki patch for irclog2html 转变成 MediaWiki pipe-tables.

WiKi 页面的结构

这一部分描述的一般 wiki 页面的结构. 每一个页面都遵循这些规则. 还有附加的规则被正式的 Fedora documentation 使用, 参考 DocsProject/WritingUsingTheWiki; 那些规则在编写 Fedora Documentation Project 的过程中需要. 页面的标准内容模板和其它不同页面可能会有不同的结构.

Note.png
Header 1 (h1) 推荐在标记中使用
header 1 定义了页面标题. 当作出新页面或迁移页面时, re-nest和re-structrue的页面只有 header2 和 header 2以下.
  • 页面的标题是第一级标题, 它自动从页面标题产生.
  • 每一章用等号对产生.
== Header 2 ==
=== Header 3 ===
==== Header 4 ====
===== Don't do this, 5 levels of nesting means you need a new page or three =====
  • 当页面增长变很大的时候表的内容自动产生和填充.
  • 锚的部分会自动创建, 在空格和标点符号地方使用了特别符号
This page ==> This_page
This, that, and the other page ==> This%2C_that%2C_and_the_other_page
Idea.png
使用锚时候用 .2C 代替 %2C
'.' 到 '%' 的替换是锚使用特别的部分.

快速技巧

这些都是编写 WiKi 你必须知道的最基本的信息.

Note.png
欲了解 WiKi 更多 文件起草的信息, 参考 Writing Wiki Documentation.

样例学习

学习如何编辑 WiKi 较好的方式是检阅存在页面的代码. 这是非常容易的:

  1. 找到你想要阅读源代码的页面
  2. 在导航栏, 找到组合框 'More Actions:', 点击它.
  3. 选择 'Show Raw Text' 选项.

页面将以 plaintext 格式显示. 学习在你之前的 WiKi 编辑所使用的技巧, 这些聪明的技巧是宝贵的, 它们很有趣很强大你是想到没有想到过的. 你可以在页面中试一试技巧.

注解, 技巧, 其它警告

这些统称为警告, 在 are used in DocBook. 要把段落放入警告中, 使用特别的警告模板. 建议使用一个简短的标题和一个较长的段落描述.


输入 显示
{{admon/note|A title|Here is more information about
this tip, with information that provides more insight
into the informative title of the initial paragraph.}}
Note.png
A title
Here is more information about this tip, with information that provides more insight into the informative title of the initial paragraph.

对初始段落和第二个段落缩进一个空格, 保证正确的对齐.

标准类型的警告:

输入 显示
{{admon/note|This is a note|Informational paragraph
that tells more about what is going on.}}
Note.png
This is a note
Informational paragraph that tells more about what is going on.
{{admon/tip|This is a tip|Informational paragraph
that tells more about what is going on.}}
Idea.png
This is a tip
Informational paragraph that tells more about what is going on.
{{admon/important|This is important|Informational paragraph
that tells more about what is going on.}}
Important.png
This is important
Informational paragraph that tells more about what is going on.
{{admon/caution|This is a caution|Informational paragraph
that tells more about what is going on.}}
Stop (medium size).png
This is a caution
Informational paragraph that tells more about what is going on.
{{admon/warning|This is a warning|Informational paragraph
that tells more about what is going on.}}
Warning (medium size).png
This is a warning
Informational paragraph that tells more about what is going on.

警告样例

使用警告标记显示内容的例子:

Note.png
Cliffs can be very high
Wikipedia can vouch for this.
Idea.png
Standing away from cliff edges is a way to stay safe
For more information, read the cliffs(1) man page.
Important.png
Keep your children away from the cliff edge to your right
Children move around quite a bit and can easily fall off. You should hold their hand.
Stop (medium size).png
You are getting near the cliff edge
As mentioned earlier, cliffs can be very high, and it would be bad to fall.
Warning (medium size).png
You are about to fall off the cliff
Move away as quickly as possible to avert falling.

参考 Fedora Documentation Guide 描述 警告标签 类型: http://docs.fedoraproject.org/documentation-guide/en_US/sn-xml-admon.html

技术术语的标记

使用 code 标签 (<code>) 标记应用程序名, 文件, 路径, 软件包, 用户帐号和其他有特别含义的单词. 被标记的单词以 monospace 显示.

使用2个单引号 ('') 标记菜单项名和其他图形接口元素, 被标记的单词以 italic 显示.

术语 标记 格式化例子
图形应用程序名
 '''boldface''' 
Firefox
文件, 路径
 <code>inline code tags</code> 
/usr/bin/firefox
软件包
 <code>package name</code> 
firefox-1.2.3
用户帐号
 <code>username</code> 
username
其他特别技术含义的单词
 <code>technical term</code> 
... the class org.fedora.someJava.classname ...
图形菜单和菜单项
 ''Menu name'' 
Applications > Internet > Firefox Web Browser
其他图形用户界面和 WebUI 接口元素
 ''two single-ticks'' 
... click the Submit button ...
内置命令和守护进程
 <code>command -option</code> <code>daemon</code>
grep httpd to find the PIDs of the running httpd processes.
Blocks of code, 配置文件等.
 <pre>whitespace preserved< /pre> 
whitespace
    is preservered
  here
Inline pieces of code, 配置文件等, etc.
 <code>inline whitespace not preserved</code> 
... Next, modify the variables for set() in /path/to/org/dev108/classname ...
First term, glossary term
 ''term'' 
... Firefox is an example of a graphical user interface or GUI.
 '''[Key]''' 
Press the [Enter] key ...

例如:

The <code>thunderbird</code> package installs the '''Mozilla Thunderbird'''
e-mail application. To start '''Thunderbird''', select:
  ''Applications > Internet > Thunderbird Email''.

显示为:

The thunderbird package installs the Mozilla Thunderbird e-mail application. To start Thunderbird, select: Applications > Internet > Thunderbird Email.

命令样例的编写

命令样例是一个命令或多个命令集.不要使用提示符或者其他显示了机器名,用户,路径等信息的内容. (这些在$PS1环境变量都设置了)

任何命令样例应该放入 <pre></pre> 标签里:

<pre>
su -c "yum install awesome-application"
</pre>

Enter the <code>root</code> password when prompted.

Which produces:

su -c "yum install awesome-application"

提示后输入 root 密码.

Note.png
命令 和 root
命令执行需要 root 权限. 读者不要以 root 登录系统, 当执行这些命令的时候必须先使用 su -csu -.

如果命令需要引用, 应当放入 " '' " 里, 单引号被双引号包围, 例如:

su -c "command -o 'Some Text' -file 'More text' foo/bar"

如过需要一系列命令或者 su -c 没有如预期的, 可用户切换到 root 并且警告用户之后要返回用户 shell.

su -
Password:
service food stop
cp /etc/foo.d/foo.conf /etc/foo.d/foo.conf.backup
vi /etc/foo.d/foo.conf
food --test-config
...
service food start
exit

命令输出样例

当样例要显示命令的输出, 应当使用命令提示符区分命令和它的输出变得清晰.

$ su -c "ls -l /root"
Password: 
total 148
-rw------- 1 root root  1961 2007-09-21 02:46 anaconda-ks.cfg
-rw-r--r-- 1 root root 46725 2007-09-21 02:46 install.log
-rw-r--r-- 1 root root  6079 2007-09-21 02:42 install.log.syslog
-rw-r--r-- 1 root root  3699 2008-07-28 17:24 scsrun.log
-rw-r--r-- 1 root root 45038 2008-01-10 10:21 upgrade.log
-rw-r--r-- 1 root root  1317 2008-01-10 10:20 upgrade.log.syslog

你自己试试

Fedora Wiki Sandbox 尝试一下. 那里可以发现很多好的小例子.


在 WiKi 建立新页面

Fedora Project Wiki 很大, 因此有必要保持一个适当的层次和组织. 最好学习方式是检阅 Help:SubpagesHelp:Categories, 然后检阅现有的 WiKi布局.

多余名字(例如Foo/FooBar/FooBarGrue)应该避免. 记住包括 'Fedora' 的页面名也是多余的. 主要的 Fedora 项目不需要有 'Project' 在它们的页面名称里. 例如, Fedora Websites 项目有它的页面名称 'Webbsites', 而不是'FedoraWebsitesProject'.

大多数情况下, 页面应该按照项目或者程序来分组. 根据不同的项目和程序来建立分类必须谨慎. 你建立的大多数页面应该有一个分类, 有合适的标签. 如果你认为要建立新的分类或者标签, 请询问 Websites 小组获取建议.

如果有任何问题, 随时联系 Websites 小组.

重要的页面

关键页面, 例如首页, 应该谨慎编辑. 修改这样的页面之前通常应该在邮件列表或者 IRC 上讨论. WiKi 的有些部分会有不同的权限, 例如, DocsProject对于新文档的产生比 WiKi 其它部分的限制更多. 为了获得这样的页面的编辑权限, 你应该完成额外的步骤,可在那些页面上找到这些指示.

获得帮助

如果你有关于编辑 Fedora Project Wiki 的问题, 或者如果你需要帮助, 请随时联系 Websites 小组. 他们有 IRC 频道 (#fedora-websites on freenode) 和 邮件列表 (fedora-websites-list), 都能对你需要给予有效的帮助.

如果你愿意对 wiki 做大量编辑, 你应该关心 joining the Websites team.