User:Junkie/Help:Editing

From FedoraProject

< User:Junkie
Revision as of 15:21, 28 November 2008 by Junkie (Talk | contribs)

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. Complete the Contributor License Agreement through the Fedora Account System. Signing the CLA gives the Fedora Project the ability to license your contributions to the wiki under the Open Publication License 1.0 without options. This assures that your contributions will remain forever Free for the community to use, modify, and redistribute, just like the Fedora distribution. See our Legal section for more information. Follow the instructions at Infrastructure/AccountSystem/CLAHowTo.
Note.png
If you are interested in more general website maintenance, or wish to be part of the Fedora Websites team, please see the Websites page.
Information on writing new formal Fedora documentation using the wiki is available from Writing Wiki Documentation.

准则和 Wiki 礼节

There are a few simple points you should follow as you make changes to the wiki. Below are some examples. In general, be courteous and use common sense. Defying these guidelines and causing problems are a good way to get your edit privileges revoked. If you have questions, you can ask on #fedora-websites on freenode.

介绍你自己

Before you start editing any page, kindly introduce yourself by adding your information to your wiki page. After you have registered your name in the wiki, you automatically have a personal wiki page located at http://fedoraproject.org/wiki/User:<username>, where <username> is replaced by your Fedora Account System account name. You can also easily get to your wiki page by clicking your username in the top right-hand corner of each page of the wiki.

For examples, take a look at some wiki pages of our contributors.

Make sure you mention at least your email address and, if you are on IRC often, your IRC nick and channels you are often in.

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

It is important that you follow changes to pages you create or edit, so you can coordinate with others working in the wiki content. Wiki editors usually add notes to the pages to convey information to each other as part of working together, and it helps to keep track of these changes.

You can find the watch link in the tab bar at the top of a page when you are logged in.

设为粗体

Be bold while editing changes. Wiki changes are tracked and can be reverted when necessary. This doesn't mean you should be reckless especially when making large changes to key documents.

For more information on being bold, take a look at the be bold editing guideline on Wikipedia.

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

These pages have been carefully written, and the words chosen carefully. When changing these documents, it is usually best to ask for review before applying changes. You can contact the Fedora Advisory Board for assistance.

不要提供详细的禁止项目

Do not add any information that violates the law. Remember that the Fedora Project is an entity in the United States, and is governed by its laws. Avoid linking to or adding information about software that is not free and open source or that is legally encumbered. If you think you have a special exception, bring it to the attention of the Websites team for discussion. See the ForbiddenItems page for examples of items that should be avoided.

Bring questions to the Websites team for discussion. If needed, they can get the official word.

小心编辑向导或页面

Large and important guides, such as the Packaging Guidelines , are generally managed by a specific individual or small group. It is best to work with them when you feel that changes are needed.

Important pages, like the FedoraMain or Download pages, are the first thing that many visitors see. Changes to such pages should generally be left to experienced contributors. If you feel that something on such a page should be altered, bring the issue to the Websites team for discussion.

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

Senseless edits should be avoided. Making an alteration to a page just to put your name in the edit log is unacceptable. There are plenty of pages (most of them, in fact) that have real errors that can be corrected. Instead of making pointless edits, such as removing or adding whitespace or changing links from fedoraproject.org to www.fedoraproject.org (the former is preferred), try finding errors in spelling, grammar or punctuation that can be corrected. Also, when correcting a small error, mark "This is a minor edit" using the appropriate checkbox before you save it.

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

Wiki pages are generally referred to and linked to from various other locations. It is important that you coordinate with the appropriate groups before moving content or renaming existing pages. It would be better to avoid doing that without strong rationale. If you wish to discuss moving a particular item, bring your questions to the Websites team.

删除页面

Wiki pages that are no longer needed can be tagged for deletion by adding {{Delete|Reason}} to the beginning of the page, this gives Wiki Administrators the ability to ensure that important or archivable content is not lost.

Follow the ideals that Fedora holds important

For example, try to remain desktop-neutral and user-friendly, especially for non-technical users who are new to Linux and to Fedora. Users may use GNOME, KDE, the console, or some other environment. Try to keep that in mind when writing instructions. Make sure that Fedora's devotion to free and open source technology is also represented properly.

对附件签名

When you attach a file to a wiki page, you should create a detached signature with your GPG key. Some file formats, such as RPM packages, support GPG keys, in which case you do not need to create a detached signature -- a signature in the file will be enough. A detached signature can be attached to the page alongside the original attachment, or can be included in the page itself.

GPG signatures allow others who download your file to verify that it came from you and has not been modified or corrupted. They do not violate your privacy in any way, they simply allow others to have confidence in the origin of your files.

Images and simple documents are safe to leave without a signature, but there would be no harm in adding one anyway to verify that you were the author.

If you do not have a GPG key or want to learn more, see the Cryptography page.

审查更改防止错误

Whether you are a skilled writer, or your English skills are not strong, invite someone else to review. Well-written documents are important to Fedora's image. Even the best writers are prone to typos or other errors. Take a moment to review your changes to catch small errors. Use the Show preview button when editing a page to check your syntax.

Fedora 是一个社区

When writing content, for the wiki or elsewhere, remember that Fedora is a community. We operate as one, unified group, moving towards common goals. We do not need to distinguish one group or class against another. For example, there is no need to distinguish between contributors who work for Red Hat and those who do not. All contributors are part of the same community. There will be cases where classification is necessary, but it can be avoided otherwise.

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

Other community members will be happy to assist you. The #fedora-websites channel on freenode is the perfect place to discuss the wiki or other Fedora websites.

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

Two details make a Wiki successful as an open content collaboration tool. First is being able to watch content you are responsible for, to make certain it stays true to its mission. Second is being able to watch other content develop, grow, and occasionally need your help.

To watch any page on the wiki, after logging in, click the watch link in the tab bar at the top of a page. It should change to unwatch after it has finished. If a page has unwatch at the top, you are already watching that page. You can click unwatch to unwatch a page.

To receive emails for every edit, go to my preferences (at the top of the page by your name) and make sure to check the appropriate boxes in the User profile tab, under Email.

使用 Special:Watchlist

Special:Watchlist (available by clicking my watchlist at the top of each page when you are logged in) displays pages you are currently watching. For more information on how to use this special page, please the manual page at Mediawiki.org.

We are now maintaining a stand-alone Watchlist_How-To to help Fedora contributors with specific suggestions and tools.

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

We all need to be able to quickly glance at a change and know the substance of it. A full diff is not always available. You must supply a summary of your change (Summary: field when editing). This is akin to a changelog message. Explain what you did and why, as well as other useful links and details.

If you choose to not put in a summary, it should be the rare exception. One reason is when doing a minor edit. In that case, be sure to check This is a minor edit when saving.

编辑 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: [1] [2]
[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 页面的结构

This section describes the common structure of a wiki page. Follow these guidelines for every wiki page. There are additional rules used for formal Fedora documentation, covered in DocsProject/WritingUsingTheWiki ; those rules are only required for content written to follow the procedures of the Fedora Documentation Project. Pages that are templates of standard content that are drawn into other pages may have a different structure.

Note.png
Header 1 (h1) deprecated for use in markup
The header 1 is defined by the page title. When making new or migrating pages, either re-nest or re-structure the page to have only header 2 and below.
  • The title of the page is a first-level header. It is created automatically from the page title.
  • Sections are created using the equals symbols in pairs:
== Header 2 ==
=== Header 3 ===
==== Header 4 ====
===== Don't do this, 5 levels of nesting means you need a new page or three =====
  • The table of contents is automatically created and populated when the page grows big enough.
  • Anchors to sections are automatically created, with specific symbols used in place of punctuation and spaces:
This page ==> This_page
This, that, and the other page ==> This%2C_that%2C_and_the_other_page


Idea.png
You can use .2C instead of %2C for anchors
The substitute of '.' for '%' works for anchors against a specific section.

快速技巧

These are the basic things that you need to know to edit this Wiki.

Note.png
For more information on drafting documentation on the Wiki, refer to Writing Wiki Documentation.

样例学习

Among the better ways to learn how to edit the wiki is reviewing the code of existing pages. This is very easy to do:

  1. Find a page whose source you would like to view.
  2. In the Navigation bar, find the combo box that reads 'More Actions:' and click on it.
  3. Select the 'Show Raw Text' option.

The wiki will display the plaintext form of that page. This is particularly valuable for learning some of the clever tricks used by wiki editors ahead of you. Those 'clever tricks' are valuable, as they allow you to do unique, interesting, and powerful things you might not have thought were possible. You might try this on pages like FedoraMain.

注解, 技巧, 其它警告

These are collectively known as admonitions, and are used in DocBook. To make a paragraph into an admonition, use the special admonition template. A short title and a longer descriptive paragraph are recommended.

What you type What you see
{{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.

Indent the initial and second paragraph by one space, to ensure that the box aligns correctly.

These are the standard types of admonition:

What you type What you see
{{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.