sBooks Publishing Guide

by Ken Haase and the sBooks team

Copyright © beingmeta, inc. 2009-2010

sbooks.net about blog beingmeta

sBooks provide a better way for your ideas to reach, engage, inform, and influence readers. Creating an sBook from your content enables people to have conversations about your ideas, connect comments with context, and add value for their friends and other readers.

The sBooks platform is built on the existing open standards of HTML and CSS. This makes it easy to both convert existing content and create new content with standard commercial or open source tools. This also makes it easy to convert an sBook into a packaged e-book for reading devices like Amazon's Kindle or O'Reilly's BookWorm.

While sBooks doesn't provide any native ability to make your books beautiful, we believe it's worthwhile paying some attention to your document style and especially the use of CSS. There are some nice examples at the ePub Zen Garden and a little effort can go along way. In addition, some reading programs (including the web-based sBooks readers) pay attention to style information about page breaks which can be helpful in making your books more attractive and readable.

sBooks work better with reasonably clean HTML and the automatic tools have an easier time when the document is actually XHTML (though it makes a good effort with straight or sloppy HTML). The output of the automatic tools is UTF-8 encoded XHTML.

Once a book is in HTML, you can make it work as a web-based sBook by just referencing the appropriate CSS and Javascript files in the header, for example:

<link rel='stylesheet' type='text/css' href='http://static.beingmeta.com/sbooks/bundle.css'/>
<script language='javascript' src='http://static.beingmeta.com/sbooks/bundle.js>
</script>

Simply including these files will automatically provide a subset of the sBooks features.

To make full use of sBooks, you'll want to add some additional information to your document, particularly:

1. document metadata (not much)
2. structural metadata (mostly automatic)
3. semantic metadata (as much as desired, partially automatic)

The automatic sBooks conversion tool can do much of this preparation automatically.

Document Metadata

Document metadata provides certain information about the book as a whole which is used in sharing glosses. These are defined via META tags in the head of the HTML document. It is strongly recommend that authors or publishers at least provide:

• a REFURI uniquely identifying the document;
• an SBOOKID to use as the prefix for element identifiers that identify passages within the document

For example, the head of this document contains:

<LINK rel='refuri' href='http://www.sbooks.net/docs/publish.html'/>
<META name='SBOOKID' content='SBOOKPUBGUIDE'/>

If the REFURI isn't specified, sBooks attempts to use the document's canonical URL. Specifying a REFURI makes it easy to change where the document is located and is crucial if bundling your book for electronic distribution.

Other document metadata includes:

• DOCURI is used when a book is divided into several HTML files; with sBooks, all of the books have the same REFURI and SBOOKID but each will have distinct DOCURI.
• SBOOKROOT is the XML ID for the root of the book's content; it defaults the element with the XML ID #SBOOKROOT or the document body.
• SBOOKSTART is where reading should start (after, for example, any preface or navigation); it defaults to the element identified as #SBOOKSTART or the SBOOKROOT.
• SBOOKDISPLAY provides default display preferences for the sBooks interface. It consists of space-separated keywords:
  • paged indicates that the book should be displayed as paged media even on devices that support vertical scrolling;
  • scroll indicates that the book should use vertical scrolling even when paged presentation is available;
  • sparse minimizes the sBooks interface, favoring smaller icons and more transparency;
  • noflash suppresses the automatic appearance of contextual information (headings, tags) as the reader moves through the text

In addition to document metadata used by reading software, other kinds of meta information can be used by external processes (such as the automatic conversion tools) or search engines. This includes the standardized metadata tags (such as DESCRIPTION or KEYWORDS).

Structural Metadata

Structural metadata is used to both construct the map used to navigate the book and to uniquely identify passages for annotation or linking. sBooks automatically uses the standard HTML header elements H1 through H7 to organize the content into a rough hierarchy. The level on an element can also be specified by assigning the element a CSS class of the form sbooklevel (e.g. sbook3 for a third level head.) The CSS class sbooknothead indicates that the element should not be treated as a head.

New structural elements can be declared in the document header through META fields SBOOKHEAD1 through SBOOKHEAD9; the content of these fields consists of simple CSS selectors separated by semicolons, so:

<META name='SBOOKHEAD1' content='div.chaphead;div.preface;div.appendix'/>

declares three new kinds of top level heads.

Identifying passages

sBooks uses XML identifiers (ID attributes) to distinguish passages within the book for sharing comments or indexing tags. Usually, these identifiers are defined automatically based on the book hierarchy. This usually happens in pre-processing but can also be generated when the document is read. In either case, this assignment is controlled by several META tags in the document header:

• SBOOKIDIFY identifies which elements should get unique IDs. Normally, all 'block level' elements are given unique IDs as do elements with the CSS class sbookidify.
• SBOOKIGNORE identifies elements which shouldn't get IDs. Normally, inline elements don't get IDs as do elements with the CSS class sbookignore.
• SBOOKTERMINALS identifies elements whose children should not get IDs. Adding an sbookterminal CSS class for an element also keeps its children from being assigned automatic IDs.
• SBOOKAUTOID tells the sBook reading software to assign IDs automatically when loading the document. This can lead to unexpected problems because the IDs may move if the document is reorganized.

Generated identifiers start with the SBOOKID specified for the book. When multiple versions of a book exist (for example, translations or updates), it can be helpful for them to have a common SBOOKID prefix and for individual IDs to be aligned.

Semantic Metadata

sBooks use fine-grained semantic tags to help readers search and browse. Tags can be applied to any section or passage and can come from either the author/publisher or external glosses. Tags are distinguished by meaning and connected by inference: shepherd:breed is connected to dog:animal and distinguished from shepherd:person and dog:epithet.

Tags can be associated with a passage or a section head by adding a tags attribute to an element. The value of the tags attribute is a list of tags separated by semicolons. sBooks also supports the Technorati tagging microformat where an HTML anchor with a rel attribute of 'tag' has the final component of its reference interpreted as a tag.

In order to officially validate as HTML or be used with certain tools, the tags attribute has the alias data-tags and can also be specified (in XHTML) in the XML namespace http://sbooks.net/. For example, this paragraph starts with the following paragraph tag:

<p sb:tags='tagging;semicolons;HTML;section heads'>

Rich tags

Tags are simple strings but sBooks provides ways to organize them into knowledge structures called knowlets and uses this knowledge in search. For example, a knowlet can store synonyms for a tag or describe relations between tags (for instance, that one tag is a generalization of another). The capabilities and syntax of knowlets are detailed here but the general syntax is very simple.

Any appearance of a tag (for example, in a TAGS attribute) can provide extra information in the form of clauses which follow the tag and are separated by vertical bars. If a clause starts with punctuation, it is treated specially; otherwise it is simply a synonym for the tag. For example, sbook tag|tag|keyword|keyphrase defines the tag sbook tag with three synonyms.

Special clauses can provide additional information beyond synonyms, for example:

knowlet|know-let|~knowlit|^knowledge base|^micro format|_embedded knowlet

introduces the tag knowlet with synonym know-let and declared 'misspelling' knowlit. It also asserts that the tags knowledge base and microformat are generalizations of knowlet and that the tag embedded knowlet is one kind of knowlet.

For more information about knowlets, visit knowlets.org.

Specifying rich tags

Knowlets can be included in an sBook in three ways:

• inline knowlets are included in tag references, as in the TAGS attribute. For example, the markup for this list item started with:

  <p tags='inline knowlet|implicit knowlet|^knowlet;TAGS attribute;>

• embedded knowlets are included in the document in a SCRIPT tag with language 'knowlet'. The body of this element consists of a sequence of tag specifications separated by semicolons.
• external knowlets are stored in external documents reference by URIs. These are also specified by a SCRIPT element but with an SRC attribute specifying the external URL. For example:

  <SCRIPT language='knowlet' src='http://library.sbooks.net/CharlesDarwin/darwin.kno'></script>