Standard Ebooks

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

  1. The first line of all XHTML files is:

    <?xml version="1.0" encoding="utf-8"?>

  2. The second line of all XHTML files is (replace xml:lang="en-US" with the appropriate language tag for the file):

    <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-US">

  3. Tabs are used for indentation.

  4. Tag names are lowercase.

  5. Elements whose content is phrasing content are on a single line, with no whitespace between the opening and closing tags and the content.

    <p> It was a dark and stormy night... </p>
    <p>It was a dark and stormy night...</p>

<br/> elements

  1. <br/> elements within phrasing content are on the same line as the preceding phrasing content, and are followed by a newline.

    <p>“Pray for the soul of the <br/> Demoiselle Jeanne D’Ys.</p>
    <p>“Pray for the soul of the <br/>Demoiselle Jeanne D’Ys.</p>
    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys.</p>

  2. The next indentation level after a <br/> element is the same as the previous indentation level.

    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys,<br/> who died<br/> in her youth for love of<br/> Philip, a Stranger.</p>
    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys,<br/> who died<br/> in her youth for love of<br/> Philip, a Stranger.</p>

  3. 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.

    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys. </p>
    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys.</p>

  4. <br/> elements have phrasing content both before and after; they don’t appear with phrasing content only before, or only after.

    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys<br/></p>
    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys</p>

Attributes

  1. Attributes are in alphabetical order.

  2. Attributes, their namespaces, and their values are lowercase, except for values which are IETF language tags. In IETF language tags, the country subtag is capitalized.

    <section EPUB:TYPE="CHAPTER" XML:LANG="EN-US">...</section>
    <section epub:type="chapter" xml:lang="en-US">...</section>

  3. The string utf-8 is lowercase.

Classes

  1. 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.

  2. Classes are named semantically, describing what they are styling instead of the resulting visual style.

    <p>There was one great tomb more lordly than all the rest; huge it was, and nobly proportioned. On it was but one word</p> <blockquote class="small-caps"> <p>Dracula.</p> </blockquote>
    <p>There was one great tomb more lordly than all the rest; huge it was, and nobly proportioned. On it was but one word</p> <blockquote class="tomb"> <p>Dracula.</p> </blockquote>

CSS formatting

  1. The first two lines of all CSS files are:

    @charset "utf-8"; @namespace epub "http://www.idpf.org/2007/ops";

  2. Tabs are used for indentation.

  3. Selectors, properties, and values are lowercase.

Selectors

  1. Selectors are each on their own line, directly followed by a comma or a brace with no whitespace in between.

    abbr[epub|type~="se:era"], abbr[epub|type~="se:temperature"]{ font-variant: all-small-caps; }
    abbr[epub|type~="se:era"], abbr[epub|type~="se:temperature"]{ font-variant: all-small-caps; }

  2. Complete selectors are separated by exactly one blank line.

    abbr[epub|type~="se:era"]{ font-variant: all-small-caps; } strong{ font-weight: normal; font-variant: small-caps; }
    abbr[epub|type~="se:era"]{ font-variant: all-small-caps; } strong{ font-weight: normal; font-variant: small-caps; }

  3. Closing braces are on their own line.

Properties

  1. Properties are each on their own line (even if the selector only has one property) and indented with a single tab.

    abbr[epub|type~="se:era"]{ font-variant: all-small-caps; }
    abbr[epub|type~="se:era"]{ font-variant: all-small-caps; }

  2. 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.

  3. Properties are directly followed by a colon, then a single space, then the property value.

    blockquote{ margin-left: 1em; margin-right: 1em; border:none; }
    blockquote{ margin-left: 1em; margin-right: 1em; border: none; }

  4. Property values are directly followed by a semicolon, even if it’s the last value in a selector.

    abbr[epub|type~="se:era"]{ font-variant: all-small-caps }
    abbr[epub|type~="se:era"]{ font-variant: all-small-caps; }

SVG Formatting

  1. SVG formatting follows the same directives as XHTML formatting.

Commits and Commit Messages

  1. 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".

  2. 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.