• Purpose
• How much should I care about how my HTML is formatted?
• The settings and their meanings
• Specifying the formatting settings for a file

Purpose

Consistent, well-formatted HTML — without having to worry about it — is a cornerstone of TypeMetal’s design philosophy.

TypeMetal’s HTML formatting settings model helps you produce tidy, professional-grade markup that you can be proud of, and that suits your taste or the guidelines of the sites you write content for. You can change your HTML formatting settings at any time. The new settings will take effect the next time you save a file to which the given set of settings applies.

Each HTML file you edit uses either your global HTML formatting settings (which you can configure in TypeMetal’s Settings panel) or its own formatting settings. By default, a file’s formatting settings are stored as custom metadata in its header, enabling them to be preserved through version control systems and similar collaboration tools, and thereby helping authors who work jointly on a file to use the same formatting.

How much should I care about how my HTML is formatted?

The results controlled by TypeMetal’s HTML formatting settings are largely stylistic choices. That is to say, they generally don’t affect the rendered appearance of your pages; they only affect what people see when they “View Source” to see the page’s HTML markup.

You may not care about this at all. If so, you can simply rely on TypeMetal’s default HTML formatting settings, which are designed to produce modern, tidy results that most people would consider pleasingly structured.

If you’re a professional web developer, collaborate with others on web projects, or are meticulous about details, you probably do care how your HTML source code is formatted. In such cases, TypeMetal’s aim is to give you the control you seek, while empowering you to “set it and forget it” via a manageably simple preference set, and thereafter not worry about markup formatting while you write and edit.

Specifying the formatting settings for a file

You can specify the formatting settings to use for an open file using either the “HTML Formatting” toolbar controls, or the File -> HTML Formatting… menu command.

Changing the setting to “Custom” gives the file its own HTML formatting settings, that will be saved in the file as part of its custom metadata. The custom settings initially match the settings in TypeMetal’s Settings panel. You can edit them to specify different formatting for the file.

Changing the setting to “(User Settings)” removes any custom formatting settings from the file’s custom metadata, causing the file to switch to using the settings you’ve specified in TypeMetal’s Settings panel.

If your use of TypeMetal is limited to a set of files that all share the same desired HTML formatting, then making your desired formatting settings once, in TypeMetal’s Settings panel, should suffice.

If you work on a variety of projects or files, that shouldn’t all conform to the same formatting settings, then you’ll find TypeMetal’s per-file formatting settings useful.

The settings and their meanings

Following are explanations of the settings that comprise a given set of HTML formatting settings. You can get an intuitive feel for what each setting does by watching the sample HTML markup to the right of the controls change as you experiment with different settings.

Generally speaking, the settings are worded to make “checked” the normal, recommended state for checkbox items. When in doubt, try starting with all settings enabled (TypeMetal’s out-of-the-box default), and work from there toward settings that produce the exact results you want. The descriptions below include advisory explanations of the consequences of each setting.

Use lowercase <element> and attribute names

When checked, elements are written with lower-case tag names and attribute names — e.g. <a href="page.html">

When unchecked, elements are written with upper-case tag names and attribute names — e.g. <A HREF="page.html">

XHTML, the formulation of HTML as XML, requires element and attribute names to always be written in lower-case, so TypeMetal disregards this setting when writing XHTML documents, and always uses lower-case. In HTML 4 and 5 document types, tag and attribute names are case-insensitive, so which to choose is a matter of preference. Lower-case tends to be the more modern usage. Upper-case was more common in the early days of the Web.

Close empty <element> tags with a /

When checked, empty elements are written with a closing slash character — e.g. <img src="screen.png"/>

When unchecked, empty elements are written without a closing slash character — e.g. <img src="screen.png">

XHTML, the formulation of HTML as XML, requires empty elements to be terminated with a / character. This is called a self-closing element. In modern HTML (HTML 5), the slash is allowed but optional. Some HTML authors choose to include it as a matter of modern style. Note that, when you're editing a file whose DOCTYPE is XHTML, this setting is ignored, and TypeMetal always terminates empty elements with a closing slash, as required.

Leave a space before the /

This setting is only relevant when “Close empty <element> tags with a /” is checked (or the file’s DOCTYPE is XHTML).

When checked, TypeMetal leaves a space before the closing slash character — e.g. <img src="screen.png" />

When unchecked, TypeMetal leaves no space before the closing slash character — e.g. <img src="screen.png"/>

Leaving a space before the closing slash improves compatibility with older browsers, at the small cost of an extra character per empty element.

Enclose attribute values in "double quotes"

When checked, TypeMetal encloses attribute values in "double quotes" — e.g. <img src="screen.png">

When unchecked, TypeMetal encloses attribute values in 'single quotes' — e.g. <img src=‘screen.png’>

This is a purely stylistic choice. Whichever quote style you use, when a quote of that kind must appear as part of an attribute’s value, TypeMetal will automatically escape the contained quote using a character entity reference, as required by HTML — e.g. <a title=“On the Proper Use of &quot;Finger Quotation Marks&quot; in Conversation” href=“http://mysite.com”>. HTML offers the choice of single- or double-quoted attribute names so that authors may avoid the hassle of having to escape quotes within entity values, by choosing the most convenient quote style for each attribute value. For consistency, and since TypeMetal automatically handles all needed character escaping for you without your having to worry about it, TypeMetal has you choose one attribute quoting convention or the other, and then applies that single convention throughout the written HTML source. (HTML also allows for attribute values to be written without quotes, so long as the attribute value does not contain certain forbidden characters, but TypeMetal favors the stylistic uniformity of always quoting attribute values.)

Put block-level <element>s on a new line

When checked, TypeMetal writes the start and end tags for block-level elements on their own lines.

When unchecked, TypeMetal writes the start and end tags for all elements without preceding line breaks, whether the elements are block-level or not.

Putting the start and end tags for block-level elements on their own lines is a common practice that tends to improve readability. If you’d prefer to generate super-compact HTML, however, you may want to uncheck this setting — possibly in addition to “Close empty <element> tags with a /“ and “Move to a new line after a <br>”. The resultant HTML will be harder on human eyes, but you’ll get smaller files that may download a bit faster.

Indent block-level <element>s

This setting is only relevant when “Put block-level <element>s on a new line” is checked.

When checked, TypeMetal indents the start and end tags of block-level elements.

When unchecked, TypeMetal aligns those start and end tags flush with the left margin (puts no leading space before them).

Indenting blocks makes for easier-to-read HTML source code, at the cost of increasing the size of your HTML files a bit. It’s recommended, but a purely stylistic choice.

Spaces per indent

Specifies the number of spaces (character positions) to use for each indentation level.

This setting is only relevant when “Indent block-level <element>s” is checked.

Use tabs

This setting is only relevant when “Indent block-level <element>s” is checked.

When checked, TypeMetal uses “tab” characters to substitute for runs of spaces.

When unchecked, TypeMetal uses spaces only (no tabs).

Using tabs makes your files more compact, especially when you use indenting of block-level elements, but people sometimes prefer not to use them, because the number of spaces a tab corresponds to can be interpreted differently on different systems.

Spaces per tab

Specifies the number of spaces (character positions) that correspond to a single tab.

This setting is only relevant when “Use tabs” is checked. When “Use tabs” is checked, TypeMetal uses tabs in place of spaces wherever possible, and this setting tells it how many spaces it can replace with a single tab character.

8 spaces per tab character is fairly standard, but not universally agreed upon.

Don’t indent <head> or <body>

This setting is only relevant when “Indent block-level <element>s” is checked.

When checked, TypeMetal doesn’t indent <head> or <body> tags.

When unchecked, TypeMetal indents <head> and <body> tags the same as other block-level element tags.

It’s fairly common practice to treat a document’s <head> and <body> as special cases and not indent them the same as other block-level elements, since they are major sections and that would mean a lot of indenting.

Leave a blank line before and after <h1>-<h6> elements

Gives you the option to make heading elements stand out and divide the content before and after a little more clearly.

This setting is only relevant when “Put block-level <element>s on a new line” is checked.

When checked, TypeMetal writes a blank line before and after a heading element.

When unchecked, TypeMetal writes heading elements the same as other block-level elements.

Move to a new line after a <br>

Makes TypeMetal insert a textual line break after each HTML line break element (<br>).

When checked, TypeMetal emits a line break after each HTML <br> that it writes.

When unchecked, TypeMetal does not emit a line break after a <br>.

Moving to a new line after writing a <br> helps illustrate the effect the <br> will have, but has no bearing on the effect of the <br>. It’s purely a stylistic choice.

Indent to same level

This setting is only relevant when “Put block-level <element>s on a new line” and “Move to a new line after a <br>” are checked.

When checked, TypeMetal indents the line after a <br>, by the same amount as the preceding line.

When unchecked, the line after a <br> begins all the way at the left margin, with no preceding space.

Write special characters … directly as characters, when possible

When checked, TypeMetal will write characters in the native document encoding whenever possible, falling back to named or numeric entity references only when it cannot.

When unchecked, TypeMetal will always fall back to named or numeric entity references for non-ASCII characters, according to the settings that follow.

Writing special characters natively makes your HTML source code easier to read — especially if you use many accented characters or special symbols — but doesn’t safeguard against those characters being misinterpreted, which can happen if a document’s character encoding isn’t correctly advertised by a Web server, or if a tool that’s parsing your HTML file doesn’t correctly detect or handle your file’s character encoding. When in doubt, the safest choice is to uncheck this option.

Write special characters … as named references, when possible

When checked, TypeMetal will write characters using HTML named entities (such as “½” for the ½ character) when possible. If “Write special characters … directly as characters, where possible” is checked, TypeMetal tries to write characters natively first, and only falls back to named character references when that isn’t possible.

When unchecked, TypeMetal will fall back to numeric entity references, instead of attempting to use named character references.

Since XHTML files are sometimes processed by XML tools that have no knowledge of HTML’s entity names, TypeMetal acts as if this box is unchecked when it writes XHTML files. This prevents problems when processing XHTML using pure-XML tools.

Write special characters … as numeric references

When TypeMetal can’t write a character natively, or as a named reference (when those options are enabled), it falls back to writing the character as a numeric entity. You can choose whether such entities are output as decimal or hexadecimal values.

Unless you’ll be processing your HTML file using a tool that has trouble with either decimal or hexadecimal numeric entities, this is a purely stylistic choice.