User:SMcCandlish/Manual of Style/Internal

Whitespace
The purpose of whitespace in code is generally to make it more readable to humans. Mediawiki has very few required (or forbidden) uses of whitespace, but it does add some complications:


 * An entire blank line is interpreted as a paragraph break, and will generate markup, even when this is inappropriate.
 * Several features of MediaWiki only work at the beginning of a separate line. This includes heading markup (,, etc., which also cannot have any content after them on the same line), list markup ( ,  ,  , and  ), and table markup ({ ,  ,  ,  , and  ). Some exceptions are table shorthand markup   and   (used on the same line as an initial   or  , respectively), and   which  follow   on the same line.
 * MediaWiki templates (what are called scripts in most other contexts) usually drop extraneous whitespace when parsing, but this is not true within the content passed as parameter values sometimes; it can take considerable experimentation to get this perfect. It also means that use of traditional code indentation in MW templates is "dangerous"; when it does not work as intended, it can generally be simulated by use of HTML comments across the line break, i.e. ending a line with , inserting the line break and indentation, then adding   and continuing with the next line of code.
 * A line break (directly entered, rather than coded inline with ) inside a list formatted with MediaWiki's own list-creation syntax (using,  ,  , or  ) breaks the list and starts a new one.
 * The  element is styled in site-wide stylesheets with some . Consequently, traditional use of this element around entire multi-line blocks of code confusingly results in the first line being indented rightward. This can be fixed by using
 * There are various other "gotchas" that will be covered below, as needed.

Using two spaces or one after a sentence
Before beginning another sentence, whether to use a single space character or two after the terminal punctuation of the last sentence remains an ongoing and long-term controversy. Do edit-war over this matter in any page, article or not. Do make edits the sole or primary purpose of which is to futz with single- or double-spacing after a full stop (period).

The background of the conflict:


 * 1) Style guides for generations have recommended double-spacing in typewritten manuscript materials for easier reading in a monospaced (non-proportional) font.
 * 2) Modern style guides advise against this practice for proportionally typeset material, including documents produced in a word-processing application, because the rationale no longer applies.

The conflict exists on Wikipedia because some editors (especially those who do a significant amount of template coding) use a monospaced font in the editing pane, while others (mostly those who work on prose content while avoiding the more "geeky" aspects of wikiwork to the extent they can) use a proportional font. Neither side is universally "correct", though the latter side is apt to incorrectly cite usability and readability studies "proving" that single spacing is faster to read. This is novel and incorrect synthesis, because the studies to date have been of proportional-font material; none ( have studied monospaced material and produced comparative data. Professional coders are almost universally in agreement that additional whitespace mades a notable difference in the ability of humans to quickly make sense of code, and it is unlikely that this view in favor of extra spacing could be so prevalent if were not correct with regard to monospaced material.

Definitely do not use more than two spaces.

Do not include any space characters at the end of a paragraph
This includes blocks of material that are not prose paragraphs, such as list items. If another content block or a blank line follows the block in question, do not put spaces after it.

Blank lines before and after headings
This is another area of dispute, though some best practices can be observed.


 * a blank line before a heading.
 * Whether to include one after it or not is subject to editorial discretion.
 * The pattern is to include one after, unless what immediately follows is one or more hatnotes, dispute/cleanup templates, images, or similar non-prose, in which case this material takes the place of the blank line. (Although some editors have been including a blank after the last of these and before the "content proper" of the section, this can undesirably push the content downward.)  Some editors prefer no blank line here at all.

Do editwar about this.

Spaces inside headings
Yet another incompletely resolved dispute is whether to give headings in the style  versus.


 * Preferable:  – The most common style in hand-edited code, and now also what VisualEditor does when creating a new heading. VE has no problem with either style, and since the former is more readable it is the de facto standard.
 * Permissible:  – Still common, and preferred by some editors.  The readability hit is very minor.

Do editwar about this.

Blank lines before and after lists, tables, block quotations, and other block elements
There is no requirement to separate block elements from preceding or following content with a blank line, but this is generally done unless that content is directly connected to the block in the narrative flow. For example, a block quotation might not have an entire blank line between it and an introduction like "According to Einstein:". Inserting one is harmless, however, and makes it easier to discern the presence of a block element, to more easily understand the paragraph structure of the document.

Regardless, consider at least a line break before and after the block content to be mandatory. In bare HTML markup, it is not required, but if someone converts that HTML to MediaWiki list or table markup, or to a template, there is a high likelihood that it will break if the block element does not begin and end on independent lines.

Blank lines between templates and the regular content
Entire blank lines are not done, however, with infoboxes, images, page- and section-top cleanup templates, disambiguation hatnotes, and other such markup claptrap. Just a line break between each and between the stack of them and the regular content is the necessary style, because extraneous blank lines in such material will push the visible content downward for no good reason. The top of an article should have no blank lines before the beginning of the content proper.

Dr. Fu Manchu is a fictional villain character introduced in a series of novels by British author Sax Rohmer during the first half of the twentieth century. The character was also featured extensively in cinema, television, radio, comic strips, and comic books for over 90 years, and has become an archetype of the evil criminal genius and mad scientist, while lending the name to the Fu Manchu moustache.

[Rest of article here.]

Use &lt;br /&gt; correctly
When inducing a line break with the HTML element, do not include space characters before or after it; these are useless.

Do not give it as " ", " ", or truly mangled formulations like " ". This just creates pointless cleanup work for others to do, and can break the syntax highlighting many editors rely on.

For lists, use a proper list; do not create pseudo-lists with. Lists are normally done with regular list markup. For special cases like use in infoboxes, you can use a template like or  (no bullets or indentation), or  or  (inline on the same line and separated by   characters).

For paragraphs, use real paragraph markup. This is usually just done with a blank line (which the MediaWiki parser turns into a properly marked-up paragraph start tag for the content the follows it. It can also be done with explicit markup in cases that require this, such as inline in a list item in a list that uses basic MediaWiki markup, e.g.:

Include a line break in the code, when you can, where one will be visible to readers
Whenever technically possible, include a line break (a CR/LF, i.e., press or ) in the markup where ever one will be visible to readers in the rendered output of most browsers. This helps editors find and edit the specific bit of content they are looking, and helps preview the eventual structure of the content without having to actually load a rendered preview of the page.

For example, put a line break in the wikicode after a, before and after block elements, and so on. Another example:

undefined

This example uses raw HTML, but it also applies to templates like. Some templates will actually if this is not done, such as  and many similar block-termination templates.

A third example is the use of templates like. While it is possible to do them in the form, this is very unhelpful for other editors. Use the following style instead, to make it immediately clear that a list is present and that it is one:

Exception: Line breaks within list items
This in-source linebreaking cannot be done within any item in a simple wiki-markup list (a list using,  , or   and   markup). All elements within such a list-item must be inline on the same line as the rest of the item, or the list will break. These lists also cannot include blank lines between list items.

Citation templates should be given in horizontal format in regular text, but in vertical format in blocks of citations at the end
A horizontal templated citation looks like this:

A vertical citation looks like:

Using vertical citations in regular text makes it difficult for editors to discern the paragraph structure and the relative size and complexity of a paragraph; one with numerous vertical citations with a large amount of source data can fill many screens of text. On the other hand, vertical citations are much easier to read in a "References" section devoted to nothing but citation data, where prose paragraphs do not exist.

Spacing of template parameters
A solid consensus has not emerged on the matter, but a de facto consensus is very clearly observable in practice:

Either of these formats, when it comes to individual parameters, can also be used in vertical citations, infoboxes, and other templates.
 * Short templates should generally be given without spaces, unless hard to read in this format:
 * Longer, detailed templates – especially citation templates, arguably our most important, most frequently reviewed and edited, and most essential to get correct – should be spaced in horizontal format:
 * The most common format:  – Clearly groups parameters and their values.
 * Also common, but disfavored as overkill by many:  – An argument has been offered that this is more accessible for both the visually impaired and those using small displays, as on mobile devices. However – as with coder preferences for double-spacing after a sentence – there isn't any reliable-source evidence for this yet.
 * Several formats are not helpful and should be used:
 * – Serves no purpose, is visually confusing, and causes unhelpful line wrapping between parts of the parameter ID (the, the parameter name, and the  ).
 * – Worse yet, adheres the starting character of the next parameter to the value of the last; this creates clumping of code that doesn't correspond to anything meaningful.
 * – Ditto.
 * – Ditto.
 * – Ditto.
 * – Run-together and difficult to understand; makes it easy to accidentally insert conflicting parameters (e.g., two date parameters), and hard to notice that a parameter is empty (did you notice, in that example?).
 * insert a space between parameter_name and a long, unbroken value, such as URLs: &#32;https://wayback.archive.org/web/20171219034128/https://www.eff.org/... – Allows the line to break just before the long string.

Empty template parameters: Remove empty template parameters unless:


 * A present but no-value parameter has a special meaning in the template in question (few templates are coded this way any longer; in more than 99% of cases a parameter being missing or being there but empty has the same effect).
 * It is a parameter that definitely should be filled because the information is required or important, but the data simply unavailable to the present editor.

Template documentation often includes copy-paste blocks of empty code to fill in. Doing this without removing dead-code parameters that will never be filled makes a mess. Worse, especially for infoboxes, it can encourage inexperienced editors to try to fill unnecessary or inappropriate parameters, often without reading the documentation to find out what the parameters are for and what form their input must take.

CSS should be readably spaced: When giving raw CSS directives, either space them out completely or clump them by directive:


 * Readable:
 * Less readable:
 * Headache:

Some quick reminders: Numbers and units must be fused together in CSS. Close the final or only directive with a semicolon, to prevent errors if someone adds another later and doesn't notice the character is missing. Multi-word values must be single-quoted, and they must be separated by commas when there's more than one. Different types of values in shortcut properties must be separated by spaces, as must class names.

Links and anchors
Remember that these features exist and are used for navigation from content to more content.

Anchors below or inside headings
Subject to ongoing dispute for several years. The nature of the dispute:


 * 1) Anchors below headings take readers who follow links to the line on which the anchor appears, in most cases and in most browsers. Some consider this a problem, because the heading above the anchor is usually not visible.
 * 2) Putting the anchor, in any form, in the heading inserts junk code into the edit summary, and depending on exact code can also make a mess of edit history, and even (if there's a coding error) the visible table of contents.
 * 3) The "obvious" solution, of putting the anchor immediately above the heading, separates the anchor from the section to which is pertains, and will cause the anchor to no longer take people to the right section if a later editor reorganizes sections in the page and doesn't notice and move the out-of-section anchors to match.

The overwhelmingly most common practice in mainspace is to include anchors headings, not inside them, to avoid confusing new editors with mangled edit summaries.

Outside articles, some editors are adamant about including anchors, somehow, inside the headings, while others are dead-set against this. See WP:Manual of Style/Accessibility/anchor tests for test cases of every known style and what it does; this has not yet been tested with screen readers, many mobile browsers, and various other scenarios. Do editwar about it, but prefer  the heading by default, as least likely to be problematic.

Linking to Wikipedia pages

 * A piped link to a "Wikipedia:" page should always give the full name of the page and, if applicable, section . At very least, use the "WP:" version with the full page name . This link should go to the real page, not a redirect.  Using a shortcut like   here is "reader-hateful", since the point is for them to get a clear indication of the name of the link target when the mouse pointer or other focus is over the link.
 * An in-text link in "Wikipedia:" (or similar, e.g. "Help:") page to another one should use the "WP:" version for brevity. Even new users figure out within moments first starts to read such pages that "WP" is short for "Wikipedia". You can use the  parameter to produce less geeky output:  produces:.
 * Shortcuts are for editors' typing convenience in talk-page and notice-board discussions, and should not usually be used in advice materials, nor in piped links. An obvious exception is a form like:   – part of how we educate new users what all these shortcuts are.  Remember that our policy, guideline, help, essay, and information pages are primarily intended for new users, not the old hands who have memorized and helped write them, so use of shortcuts in them as if they're already understood defeats the purpose.
 * In the rare event of a mainspace link to a "Wikipedia:" page (e.g., in an article about Wikipedia itself, or in a disambiguation hatnote at the top of an article), always use the full name of the real page, without any abbreviation or redirecting:.

Piped links
Piped links should be done in the most concise manner, e.g.  not.

It is not necessary to bypass every redirect, and doing so may be undesirable, especially if a future article might be created. E.g. if Papageno exists as a redirect to The Magic Flute, then just use, not. (For more information, see

The format  is easier to instantly understand as a piped link any time the lead word of the article title is not a proper name; the capitalization is itself a "this is a piped link" indicator. It also helps find incorrectly capitalized links that are not piped, as in " " Any such capitalized link should be at the start piped, a proper name, or at the start of a sentence. When the page is veering back and forth between things like  and   this visual cleanup scanning becomes more difficult.