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.

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. 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.2. Describing changeset graphs and other diagrams

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

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

CategoryWiki