XHTML, CSS, and SVG Code Style
The se clean
tool in the Standard Ebooks toolset formats XML, XHTML, CSS, and SVG code according to our style guidelines. The vast majority of the time its output is correct and no further modifications to code style are necessary.
XHTML formatting
The first line of all XHTML files is:
The second line of all XHTML files is (replace
xml:lang="en-US"
with the appropriate language tag for the file):Tabs are used for indentation.
Tag names are lowercase.
Elements whose content is phrasing content are on a single line, with no whitespace between the opening and closing tags and the content.
<br/>
elements
<br/>
elements within phrasing content are on the same line as the preceding phrasing content, and are followed by a newline.The next indentation level after a
<br/>
element is the same as the previous indentation level.The closing tag of the phrasing content broken by a
<br/>
element is on the same line as the last line of the phrasing content.<br/>
elements have phrasing content both before and after; they don’t appear with phrasing content only before, or only after.
Attributes
Attributes are in alphabetical order.
Attributes, their namespaces, and their values are lowercase, except for values which are IETF language tags. In IETF language tags, the language subtag is capitalized.
The string
utf-8
is lowercase.
Classes
Classes are not used as one-time style hooks. There is almost always a clever selector that can be constructed instead of taking the shortcut of adding a class to an element.
Classes are named semantically, describing what they are styling instead of the resulting visual style.
CSS formatting
The first two lines of all CSS files are:
Tabs are used for indentation.
Selectors, properties, and values are lowercase.
Selectors
Selectors are each on their own line, directly followed by a comma or a brace with no whitespace in between.
Complete selectors are separated by exactly one blank line.
Closing braces are on their own line.
Properties
Properties are each on their own line (even if the selector only has one property) and indented with a single tab.
Where possible, properties are in alphabetical order.
This isn’t always possible if a property is attempting to override a previous property in the same selector, and in some other cases.
Properties are directly followed by a colon, then a single space, then the property value.
Property values are directly followed by a semicolon, even if it’s the last value in a selector.
SVG Formatting
SVG formatting follows the same directives as XHTML formatting.
Commits and Commit Messages
Commits are broken into single units of work. A single unit of work may be, for example, "fixing typos across 10 files", or "adding cover art", or "working on metadata".
Commits that introduce material changes to the ebook text (for example modernizing spelling or fixing a probable printer’s typo; but not fixing a transcriber’s typo) are prefaced with the string
[Editorial]
, followed by a space, then the commit message. This makes it easy to search the repo history for commits that make editorial changes to the work.