#pragma section-numbers 2 = Wiki Style Guide = This is a style guide to help us make the form of pages on the wiki more consistent. <> == 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' In general, it's preferrable to use singular for page names. For example, [[Subrepository]] is better than [[Subrepositories]]. 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: {{{ [[InformationForDevelopers|information for developers]] }}} 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: {{{ #REDIRECT NewPageName }}} == General form == Pages should have the following general form: {{{ #pragma section-numbers 2 = Page Title = A brief overview. <> == Section 1 == Section 1 text. == Section 2 == Section 2 text. ---- CategoryA CategoryB }}} 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. ---- CategoryA CategoryStub }}} Please be sure pages are added to appropriate categories. === D * CategoryWiki - meta-information about working on the wiki === Pages intended only for developer use (especially for upcoming features) should be marked with the following at the top of the page: <> {{{ <> }}} Similarly, pages on features that haven't been ratified should consider a marker like the following immediately after the title: This is a proposed feature, last updated Oct 2010. Be sure to link to CategoryDeveloper and CategoryNewFeatures as appropriate. == 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 === 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. === Jargon === See Mercurial's [[Topic:glossary|built-in glossary]] for accepted terminology for common Mercurial concepts. === Linking to builtin help === Links to command help should use [[InterWiki|interwiki]] links like this: [[Cmd:annotate|help on annotate]] {{{ [[Cmd:annotate|help on annotate]] }}} Similarly, links to built-in help topics should look like this: [[Topic:revsets|help on revsets]] {{{ [[Topic:revsets|help on revsets]] }}} === 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. === 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`' }}} === Referring to configuration files and other files === Files (eg ''`.hg/hgrc`'') should be referred to using monospace italic: {{{ ''`.hg/hgrc`'' }}} === Describing changeset graphs and other diagrams === The Mercurial wiki has a built-in facility for [[DrawingGraphs|drawing arbitrary graphs]]: {{{#!dot digraph G { rankdir=LR node [shape=box] a -> b -> c -> d -> e d->f } }}} === Discussion === Questions or discussion about content should be moved to a subpage named Talk, eg [[WikiStyleGuide/Talk|WikiStyleGuide/Talk]], though generally such discussion is even better directed to the [[MailingLists|mailing lists]] or [[IRC|IRC]]. === Icons === We use some of Moin's icons regularly: || {i} || {{{ {i} }}} || tips and hints || || || {{{}}} || alerts || || /!\ || {{{/!\}}} || warnings and common mistakes || || {X} || {{{ {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) === Other === By default, you should consider [[http://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style|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. == 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) == 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 == "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 }}} == 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 * CategoryNewFeatures - Development plans and other speculative pages * CategoryOldFeatures - Page from the above Categories that have been implemented or abandoned == 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 [[http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes|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. Do not link to English categories, as that will automatically pollute the English category pages. Instead link to a corresponding category for that language, eg FrenchCategoryWindows. Translations should be linked from the original page via a list below the category list: [[FrenchWikiStyleGuide|Français]], [[JapaneseWikiStyleGuide|日本語]] {{{ [[FrenchWikiStyleGuide|Français]], [[JapaneseWikiStyleGuide|日本語]] }}} Translations should also include a a similar link back to original English page, which may be more current. {i} Translators should consider using the 'Subscribe' action to track changes to the original page and keep their translations updated. == 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 == See also == * WikiCleanup - strategy for improving wiki content * TrustedEditorGroup - list of editors who have read this page ---- CategoryWiki [[ChineseWikiStyleGuide|中文]]