Skip to main content

Coding Style

All Mozilla code has a set of coding style guidelines. Issues not covered in that document are left to the module owner's choice. This document standardizes those choices in Help source code, ensuring that it retains a uniform coding style and layout, thereby aiding clarity and ease of editing.

Draft 1.0
Jeff Walden

Quick Summary

Mozilla Guidelines

As there is no pressing reason not to follow the mozilla.org guidelines, these guidelines are non-negotiable for Help code. This document lists the most up-to-date guidelines as of this page's last modification; for current guidelines please visit the Mozilla style guidelines. Actually, only a few guidelines apply to Help source code: specifically, these issues are tabs and line length. Tabs have no defined length, so they don't mesh well with Bonsai and printing. Avoid them at all costs — use two spaces instead. Long line lengths can also disrupt Bonsai and printing, so keep line lengths to 80 characters or less except in a very few small cases (DOCTYPEs, stylesheet <link>s in <head>, or structure requires it, for example — check if you aren't sure sure).

Format

All Help documents are written in valid XHTML. Using XHTML keeps information separate from layout, enforces basic coding requirements such as well-formedness and clarity, and yet is still as simple to write as HTML. There are a few considerations to make when writing XHTML Help documents. First, all documents will use the optional XML prolog to more easily distinguish XHTML documents from their HTML predecessors. Second, Help documents will not include any HTML "hacks" (such as using <br /> instead of <br/>). Third, Help documents will import a supplementary DTD for using special entities. This also means that due to validator limitations, Help documents will not automatically validate. The solution to this is to set the document type explicitly to XHTML 1.1 in the validator interface. This will still erroneously generate errors, but as long as the first two errors are for the unusual DOCTYPE and all others are for incorrect entity substitution (such as &brandFullName; for the full product name), the document should in fact be valid. Also, the page will not display when loaded in the Help viewer, adding another layer of protection.

All documents must be written in the UTF-8 encoding. Each must start with an XML prologue and an XHTML 1.1 DOCTYPE declaration (along with any external DTD imports, such as for &brandShortName; and &brandFullName;):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
  "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"[
  <!ENTITY % brandDTD SYSTEM "chrome://global/locale/brand.dtd">
  %brandDTD;
]>

Whitespace/Indentation

Whitespace aids in code clarity, but it must be used carefully. Help documents have several whitespace rules to preserve clarity and emulate the way a page will look for the end user.

Use an empty line between all block elements. This source code formatting is similar to the actual formatting of the rendered document, and it will help visualize the way the document will actually look to end users. Inline-block items like <img> must also be separated this way. Do not use blank lines between <html>, <head>, <body>, and their neighboring tags; a simple newline will suffice. Inside inline (text-level) elements, simply lay out the contents continuously, as if the contents were simply text. Wrap contents at a maximum of 80 characters and continue on the next line, indented two spaces. Compact all whitespace into single spaces (excluding line endings).

In general most of Help code is indented in some way. Several tags, however, must never be indented: <html>, <body>, and <head>. Excepting children of <body> and <head>, all other block-level tags (whether descendant or not) must be indented in proportion to how deeply they are nested. The amount of indentation is exactly two spaces; do not use the tab character for any indentation. Additionally, continuous inline content must be indented on all lines after the first:

<p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. In quis ligula. Maecenas
  nulla odio, euismod at, varius non, congue bibendum, enim. Maecenas laoreet sagittis
  est. Suspendisse volutpat. Vestibulum cursus. Phasellus vitae dui molestie metus
  congue consequat. Donec neque. Cras non urna nec enim aliquam tincidunt. Nullam
  aliquam odio eu nisl. Ut magna. Sed neque.</p>

Images

All images must specify alt text for accessibility purposes and height and width via attributes. Per accessibility guidelines, keep in mind that alt text should serve as a replacement for an image and not as a tooltip! The optional title attribute is used for tooltips; for more complicated images it is strongly encouraged.

Giving an image a text caption is often a good idea if the image relates directly to a specific point in the text. Be careful not to overuse captions, however, as they may detract from the images. Never include a caption as part of the image itself, as this is inaccessible and wastes space.

The id Attribute

The id attribute is very useful. It can be used superfluously, though, so its use is restricted in Help documents. Specifically, the id attribute should only be used when a specific element needs to be styled using CSS or when the element serves as the target of a link from an RDF or XHTML document.

The syntax of ids is this: first, eliminate all words not needed to convey the meaning of the element from the text content of the element (or the textual representation of an image if necessary). Second, replace all spaces between words with underscores. Finally, lowercase the whole string. This is your id. For example, the phrase "Setting Your Home Page in the Options Panel" would become "setting_home_page_in_options". Note that sometimes meaningful words ("Panel") are eliminated if they aren't really necessary to understanding meaning.

In this section:

Document outlines at the top of Help documents are useful for end users who want to skim for useful information. For Help documents, the "In this section" box serves this purpose. When coding these, there are a few rules: first, they exactly follow the layout of the headers in the document (excluding the title <h1>) in order. As the links are also in nested lists, link nesting should correspond to header levels. For an example of this, simply view the outline of any Help document generated by the W3 validator. Link text need not correspond exactly with heading text; extraneous words may be removed if it is deemed necessary.

Headers and Titles

Headers and titles have a few special issues beyond those of normal text. First, their main words must be capitalized. This usually would include every word except for prepositions and conjunctions in the text, but it may apply to other words depending on situation. Second, they must be properly nested: the page title must be <h1>, all second-level headings must be <h2>, et cetera. As headers are always mentioned in "In this section" parts of documents, they must also always have id attributes (excluding the page title, which is never linked).

Tables

Tables must only be used for storing data; CSS should be used for all layout.

Within tables, however, a few accessibility considerations exist. First, all header cells should be <th> cells, not <td> cells. Table header cells will be automatically styled using CSS, so it is not necessary to put their content within a <strong> element for any look (which would, in fact, violate these rules). Table headers should also be properly marked up: table rows that contain headers should be enclosed in the <thead> tag. Correspondingly, the table body should be enclosed in a <tbody> tag.

Two final accessibility issues are worth mentioning: the summary attribute and the <caption> tag. Neither is required, but each is worth considering for particularly complex tables.

Common Strings as Entities

Some strings in Help documentation are used either frequently or in special situations. Due to localization and platform constraints, keyboard modifier keys must always be written as entities:

Instead of this: Use this:
<kbd>Ctrl</kbd> &ctrlKey;
The "accel" key (<kbd>Ctrl</kbd> on Windows and Linux, <kbd>Cmd</kbd> on Mac) &accelKey;
The "alt" key (<kbd>Alt</kbd> on Windows/Linux, <kbd>Opt</kbd> on Mac) &altKey;
<kbd>Shift</kbd> &shiftKey;
<kbd>Enter</kbd> &enterKey;
preference/option &pref.singular;
preferences/options &pref.plural;
Preference/Option &pref.singularCaps;
Preferences/Options &pref.pluralCaps;
The appropriate menu path to options &pref.menuPath;
http://www.mozilla.org/projects/firefox/help/1.1 &images.baseURL;

The reasons for doing this are both obvious and subtle:

  • It makes getting things right on all platforms far, far easier than otherwise. Instead of having to special-case each modifier key every place it's used, we can just use one short entity in each place. Previously, we just used Ctrl everywhere, and that was completely wrong on Macs. This new way means we get platform-specific accuracy and nomenclature for low cost. (Curious why Ctrl and Shift are in entities? Consistency.) There is one caveat, however: we have to be absolutely certain whether to use &ctrlKey; or &accelKey;, as they have different semantics. Unfortunately, the only way to do this is to read the code — there's no centralized list of shortcut keys. The same rationale applies to the various preference/option entities, which let us use the correct nomenclature based on the platform. This system is also localizable — previous systems to do this weren't localizable such that one language pack would work on all platforms, which created problems.
  • The location for images is in an entity to make updating it for new versions of Firefox easy. It has no other real value.

Lists

In Help documentation lists are somewhat tricky issues. In some instances, such as when a list requires a certain order, the exact type of list to use is self-evident: <ol>. In other case, though, such as when a list of options is being defined, the lines become blurry: the list is a relatively unordered list (<ul>), but it's also a definition list (<dl>). In these circumstances either option could probably be argued to be correct. As standards are good to ensure this sort of nitpicking is minimized, in Help documents, if a list is a list of terms with definitions, such as a list of preferences, the only type of list used will be <dl>. <ul> will only be used when the list in question is unordered and no options are being declared and defined — this will mostly likely be a rare occurrence. (This definition is extremely likely to change as time passes to better fit the actual situations that arise.)

Use the Correct Element

While writing code, sometimes special types of text should be marked up to indicate their purpose to the end user. The current list of such text is as follows:

Keyboard input

Keyboard input includes text typed into dialog boxes, shortcut keys, and other keypresses. Input should be surrounded by <kbd> elements. For keyboard shortcuts, only the keys should be in the element; any symbols separating multiple keypresses ("+") should not be enclosed.

Emphasized text

Any text that would be emphasized if spoken should be marked up with the <em> tag to indicate that it should be emphasized. Text must not be enclosed in an <em> tag simply to italicize it.

Strong text

Any text that is strongly worded or of particular importance should be marked up with the <strong> tag to indicate that it is important and should be strongly meant. Text must not be enclosed in a <strong> tag simply to bold it.

Buttons and other interactive parts of the UI

Buttons and interactive parts of the UI (excluding menus) should be enclosed in the <em> element for now; this may change in the future to something more flexible.

Menu text and selections

Any reference to a menu, menu item, or menu selection should be appropriately noted. The proper way to do this is through use of the <span> tag with a class attribute of value menuItem. The menu selection will be styled through CSS. The reasons for this are twofold: first, consistent menu notation will ease the reading of end users, and two, it will make the jobs of localizers easier by separating out the more easily-parsed menu items from the more complex regular language.

In Help code the standard form for citing menu items has been arbitrarily decided as Menu > [Submenu >] Menu Item (encased within a <span class="menuPath"> to keep consistency with the Mozilla Firefox site.

Special Characters

Occasionally, the need may come for a Help document to include an ampersand or an angle bracket, or some other character with special meaning in XHTML. These characters must be written as entities, as must most other special characters (e.g., —, ', "). In general, if a character is not on a standard English 101-key keyboard or it has special meaning in XHTML, then write it as an entity.

Feedback is welcomed.