|
Size: 9232
Comment: 2%
|
← Revision 3 as of 2010-12-29 08:27:26 ⇥
Size: 9381
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 22: | Line 22: |
| Page titles should be 'book title capitalized': * 'OSXTips' becomes 'OS X Tips' * 'AnInterviewWithAVampire' becomes 'An Interview with a Vampire' * '1.7Sprint' becomes '1.7 Sprint' The page title should match the page name aside from the differences in style noted above. Page names and titles should favor spelling out acronyms. When there is a common acronym for all or part of the page name/title, it should be included in parentheses in the page title. Example: * 'MqExtension' (title: 'Mercurial Queues Extension') becomes 'MercurialQueuesExtension' (title: 'Mercurial Queues (MQ) Extension') To link to a page, you should generally use appropriate lowercase as the anchor text: |
标题应该用 '图书式大书': * 'OSXTips' 得是 'OS X Tips' * 'AnInterviewWithAVampire' 得是 'An Interview with a Vampire' * '1.7Sprint' 得是 '1.7 Sprint' 页面标题应该和页面名称(URL)相吻合. 页面标题/名称应该有助于缩写的阐述而不是相反.也就是说如果包含一个通用缩写的话，应该在标题中注明，而不是直接使用:: * 'MqExtension' (标题: 'Mercurial Queues Extension') 应该 'MercurialQueuesExtension' (标题: 'Mercurial Queues (MQ) Extension') 链接到一个即有页面,应该使用维基语法将标题文字作为链接给出(而不是直接使用 WikiName 格式的页面名): |
| Line 40: | Line 40: |
| If the same term appears multiple times on a page, link only the first appearance. === Renaming pages === When renaming an existing page to comply with the naming convention, please add a redirect from the old page to the new one of the form: |
如果这一链接在同一页面会多次出现,仅在首次出现时应用链接. === 重命名页面s === 当不得以重命名旧页面时,请在旧页面中使用重定向命令,导向新页面: |
| Line 50: | Line 50: |
| == General form == Pages should have the following general form: |
== 通用格式 == 所有文章,应该从以下通用格式开始:: |
| Line 56: | Line 57: |
| = Page Title = A brief overview. |
##头部 #引出的一般是维基格式化声明,一般不用改动; = 页面标题 = 概述 |
| Line 61: | Line 64: |
== Section 1 == Section 1 text. == Section 2 == Section 2 text. |
## 标题索引块 == 章节 1 == 章节 1 正文. == 小节 2 == 小节 2 正文. |
| Line 72: | Line 76: |
}}} <!> Select NewPageTemplate to get this template when creating a page. Pages with only a couple paragraphs of text may collapse this to: {{{ = Page Title = Full text. |
## 分类A/B }}} <!> 每次创建新页面时选择 NewPageTemplate 来使用这一模板. 若页面仅有一个段落就也可以:: {{{ = 页面标题 = 所有正文. |
| Line 88: | Line 93: |
| Please be sure pages are added to appropriate categories. === Development plans and other speculative pages === Pages intended only for developer use (especially for upcoming features) should be marked with the following immediately after the title: |
<!> 请确定的将所有页面都加入到合适的分类中. * MoinMoin 已经优化了这一操作,在编辑界面中底部就有一个分类选择器! * 也可以到 CategoryCategory 中参考,直接复制使用 === 开发计划和其它特殊页面 === 若页面仅用于开发人员使用(比如说未来特性的说明)应该在标题之后注明: |
| Line 100: | Line 107: |
| Similarly, pages on features that haven't been ratified should consider a marker like the following: | 同理, 如果内容还没有通过审批,应该紧跟其后注明: |
| Line 105: | Line 112: |
== Content considerations == The wiki is intended as a primary source of documentation, not as an informal discussion. Thus, wiki pages should aim to use a formal third-person style. === Version numbers === |
并对这类页面缀上 CategoryDeveloper ^开发分类^和 CategoryNewFeatures ^特性分类^ == 内容约定 == 本维基是作为正式文档来维护的,不是讨论场所,所以,应该使用第三人称进行书面化撰写. === 版本数字 === |
| Line 283: | Line 292: |
| Other Languages: [[ChineseWikiStyleGuide|中文]],[[WikiStyleGuide|En]] ---- CategoryWiki |
Other Languages: [[ChineseWikiStyleGuide|汉]],[[WikiStyleGuide|En]] ---- CategoryWiki CategoryChinese |
维基风格手册
这是确保当前维基所有文章的风格保持一致性的重要手册! 所有进行翻译的同学们,一定要认真理解!
Contents
1. 文章命名和链接规约
文章命名必须吻合 WikiCamelCase 维基驼峰式 以便编辑和读者不用专门识别文章非语义的内容, 以下是一些示例:
- 'hg' 要变成 'Hg', 'mq' 变成 'Mq'
- 'OS X tips' 变成 'OSXTips'
- '1.7 sprint' 变成 '1.7Sprint'
- 'mod_wsgi' 变成 'ModWSGI'
- 'An Interview with a Vampire' 变成 'AnInterviewWithAVampire'
通常使用单数形,比复数式,要靠谱,例如: Subrepository 比 Subrepositories 要好.
标题应该用 '图书式大书':
- 'OSXTips' 得是 'OS X Tips'
- 'AnInterviewWithAVampire' 得是 'An Interview with a Vampire'
- '1.7Sprint' 得是 '1.7 Sprint'
页面标题应该和页面名称(URL)相吻合.
页面标题/名称应该有助于缩写的阐述而不是相反.也就是说如果包含一个通用缩写的话，应该在标题中注明，而不是直接使用::
'MqExtension' (标题: 'Mercurial Queues Extension') 应该 'MercurialQueuesExtension' (标题: 'Mercurial Queues (MQ) Extension')
链接到一个即有页面,应该使用维基语法将标题文字作为链接给出(而不是直接使用 WikiName 格式的页面名):
[[InformationForDevelepers|information for developers]]
如果这一链接在同一页面会多次出现,仅在首次出现时应用链接.
1.1. 重命名页面s
当不得以重命名旧页面时,请在旧页面中使用重定向命令,导向新页面:
#REDIRECT NewPageName
2. 通用格式
所有文章,应该从以下通用格式开始::
#pragma section-numbers 2 ##头部 #引出的一般是维基格式化声明,一般不用改动; = 页面标题 = 概述 <<TableOfContents>> ## 标题索引块 == 章节 1 == 章节 1 正文. == 小节 2 == 小节 2 正文. ---- CategoryA CategoryB ## 分类A/B
每次创建新页面时选择 NewPageTemplate 来使用这一模板.
若页面仅有一个段落就也可以::
= 页面标题 = 所有正文. ---- CategoryA CategoryStub
请确定的将所有页面都加入到合适的分类中.
MoinMoin 已经优化了这一操作,在编辑界面中底部就有一个分类选择器!
也可以到 CategoryCategory 中参考,直接复制使用
2.1. 开发计划和其它特殊页面
若页面仅用于开发人员使用(比如说未来特性的说明)应该在标题之后注明:
This page is intended for developers.
<!> This page is intended for developers.
同理, 如果内容还没有通过审批,应该紧跟其后注明:
This is a proposed feature, last updated Oct 2010.
Be sure to link to CategoryDeveloper and CategoryNewFeatures as appropriate. 并对这类页面缀上 CategoryDeveloper 开发分类和 CategoryNewFeatures 特性分类
3. 内容约定
本维基是作为正式文档来维护的,不是讨论场所,所以,应该使用第三人称进行书面化撰写.
3.1. 版本数字
Versions of Mercurial younger than one year (ie three major releases) are considered new, and references to their features should include a version number. Such reference should eventually be dropped.
3.2. Jargon
See Mercurial's built-in glossary for accepted terminology for common Mercurial concepts.
3.3. Linking to builtin help
Links to command help should use interwiki links like this:
[[Cmd:annotate|help on annotate]]
Similarly, links to built-in help topics should look like this:
[[Topic:revsets|help on revsets]]
3.4. Emphasis
Generally, use italics for normal emphasis rather than bold. Bold may be useful for diagnostic check-points to help our more patience-impaired users.
3.5. Referring to commands
Commands should generally be described as a sequence of operations and their typical output in a preformatted block:
$ hg init $ hg add foo foo: No such file or directory
When referring to commands inline (eg 'hg revert -a'), use quoted monospace:
'`hg revert -a`'
3.6. Referring to configuration files and other files
Files (eg .hg/hgrc) should be referred to using monospace italic:
''`.hg/hgrc`''
3.7. Describing changeset graphs and other diagrams
The Mercurial wiki has a built-in facility for drawing arbitrary graphs:
3.8. Discussion
Questions or discussion about content should be moved to a subpage named Talk, eg WikiStyleGuide/Talk, though generally such discussion is even better directed to the mailing lists or IRC.
3.9. Icons
We use some of Moin's icons regularly:
{i}
tips and hints
<!>
alerts
![/!\](/moin-static/modernized/img/alert.png "/!\")
/!\
warnings and common mistakes
{X}
dangerous commands and content marked for removal
(./)
completed items on development plans and todo lists
(in general, use of Moin's actual smiley icons should be avoided)
3.10. Other
By default, you should consider Wikipedia's Manual of Style for resolving other fine points of style. If a point is encountered often enough in our wiki, consider adding a section for it here.
4. Mercurial naming conventions
- The program and project name is 'Mercurial' (capitalized)
- It may be abbreviated as 'hg' (lowercase), which may be capitalized at the beginning of a sentence
- The command name is 'hg' (lowercase), which is never capitalized, and should generally be quoted
- The package name is 'mercurial' (lowercase)
- The MQ extension is 'MQ' (uppercase)
5. Section headings
- Page titles should use a level one header and be book title capitalized
- Top level sections should use a second level header and start with a capital letter
- Subsections should use a third level header and start with a capital letter
- Use "#pragma section-numbers 2" to get automatic section numbering
6. "See also" sections
If a page wants to include a list of other relevant pages, it should use a "See also" section. This should be a second level header containing a list of other pages as the last section on the page:
... == See also == * WikiStyleGuide - how to style wiki pages * WikiCleanup - strategy for improving wiki content ---- CategoryWiki
7. Useful categories
CategoryStub - placeholder pages
CategoryIncomplete - pages with incomplete sections
CategoryProposedDeletion - pages we might want to delete
CategoryAudit - pages to be audited for style and content
CategoryProject - pages for work on the project that are not intended for end-user consumption
CategoryInternals - pages detailing Mercurial's internal workings
CategoryDeveloper - pages aimed at Mercurial contributors
CategoryWiki - meta-information about working on the wiki
8. Translating pages
Do not add original content in non-English languages, we can not check it for accuracy
Translated pages should prefix the original page name with the English name of the target translation language. For instance, Tutorial should become FrenchTutorial for a French translation. Please add the iso-639-1 language code on top of the page (see HelpOnLanguages). For example, on a page written in French add
#language fr
on the first line of the wiki text of the page. Translated pages should not add themselves to the English category pages, they should instead create their own parallel category pages.
Translations should be linked from the original page via a list below the category list:
[[FrenchWikiStyleGuide|Français]], [[JapaneseWikiStyleGuide|日本語]]
Translations should also include a a similar link back to original English page, which may be more current.
Translators should consider using the 'Subscribe' action to track changes to the original page and keep their translations updated.
9. Home pages
Home pages for wiki editors should:
be included in CategoryHomepage
- be predominantly English
- be predominantly related to Mercurial
- include some contact info (name, email address, IRC handle)
They should not:
- interfere with the namespace
be used as a WikiSandBox
- include non-Mercurial content like resumes
- include more than a couple off-wiki links
10. See also
WikiCleanup - strategy for improving wiki content