Wiki Style Guide

This is a style guide to help us make the form of pages on the wiki more consistent.

1. General form

Pages should have the following general form:

= Page Title =

A brief overview.

<<TableOfContents>>

== Section 1 ==

Section 1 text.

== Section 2 ==

Section 2 text.

----
CategoryA CategoryB

Pages with only a couple paragraphs of text may collapse this to:

= Page Title =

Full text.

----
CategoryA CategoryStub

Please be sure pages are added to appropriate categories.

1.1. 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:

This page is intended for developers.

<!> This page is intended for developers.

Similarly, pages on features that haven't been ratified should consider a marker like the following:

This is a proposed feature, last updated Oct 2010.

Be sure to link to CategoryDeveloper and CategoryNewFeatures as appropriate.

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

2.1. Jargon

See Mercurial's built-in glossary for accepted terminology for common Mercurial concepts.

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

2.3. 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`'

2.4. Referring to configuration files and other files

Files (eg .hg/hgrc) should be referred to using monospace italic:

''`.hg/hgrc`''

2.5. Describing changeset graphs and other diagrams

The Mercurial wiki has a built-in facility for drawing arbitrary graphs:

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

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

3. 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)

4. Page naming and linking conventions

Page names should all conform to WikiCamelCase so that editors and users don't need to remember the non-semantic content of page names. Some corner cases:

• 'hg' becomes 'Hg', 'mq' becomes 'Mq'
• 'OS X tips' becomes 'OSXTips'
• '1.7 sprint' becomes '1.7Sprint'
• 'mod_wsgi' becomes 'ModWSGI'
• 'An Interview with a Vampire' becomes 'AnInterviewWithAVampire'

Page titles, in contrast, should be 'book title capitalized':

• 'OSXTips' becomes 'OS X Tips'
• 'AnInterviewWithAVampire' becomes 'An Interview with a Vampire'
• '1.7Sprint' becomes '1.7 Sprint'

To link to a page, you should generally use appropriate lowercase as the anchor text:

  [[InformationForDevelepers|information for developers]]

4.1. 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:

#REDIRECT NewPageName

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
• Don't bother with numbering sections - it's tedious to edit

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

7. Translating Pages

Translated pages should prefix the original page name with the name of the target translation. For instance, Tutorial should become ItalianTutorial for an Italian translation. Please add the iso-639-1 language code on top of the page (see HelpOnLanguages). For example, on a page written in Italian add

#language it

on the first line of the wiki text of the page.

Translators should consider using the 'Subscribe' action to track changes to the original page and keep their translations updated.

CategoryWiki