Welcome to Lexcycle Developer Central

The Lexcycle Stanza reading platform is a way for an end user to read books. It is also a way for content creators and distributors to provide easy access to the thousands of Stanza users, as well a means for hardware and software vendors to access and extend the book import and export capabilities that Stanza Desktop provides.

At this time, we provide the documentation and the facilities for enabling content creators and distributors to publish their online books in a simple catalog format.

Who Is The Lexcycle Catalog For?

Integrating with the Lexcycle Atom Distribution System is targeted at anyone who wants to get their content available to the thousands of Stanza iPhone/iPod users around the world. While it can be used for the distribution of complete free or out-of-copyright works, it is also an attractive option for publishers who would like to provide previews or sample chapters of their books to users as a means of promoting their commercial publications. Any kind of textual content can utilize the Lexcycle Atom Distribution System; books, magazines, newspapers, essays, blogs, poetry, and religious texts are all prime candidates for distribution via this mechanism.

The Lexcycle Stanza Catalog Format

Users of Stanza for the iPhone or iPod Touch, in addition to being able to access their books from Stanza Desktop, are also able to access the online Lexcycle Catalog. Currently, the catalog offers a number of free titles, some hosted by lexcycle.com, and others offered by partner sites such as feedbooks.com, bookglutton.com, and smashwords.com. This feature might best be understood by viewing the demonstration movie at http://www.lexcycle.com

The mechanism through which Stanza accesses the distributed catalog has three components: content in the ePub/Open eBook format or the eReader format, XML catalog metadata, and an HTTP transport for the catalog. Expertise in these areas is not a requirement for implementing your own catalog, but some familiarity is recommended. The remainder of this document will discuss each of those components in turn.

The Book Format: Open eBook/ePub

ePub, also known as Open eBook, is the only standardized electronic book format available. It is flexible, enjoys high compression, and utilizes standardized technologies (XHTML, CSS, Dublin Core, and ZIP) that are familiar to many developers. Since ePub is a relatively new standard, most existing titles are in other — often proprietary — formats such as Mobipocket, Microsoft LIT, Sony LRF, or Amazon Kindle. However, Open eBook format is making gains and already has support in such products as Stanza, Adobe Digital Editions, Calibre, FBReader, Openberg Lector, and Mobipocket.

The Open eBook standard is created and managed by the International Digital Publishing Forum (IDPF). Their site should be your primary reference for creating and managing your books in the Open eBook format; they freely publish detailed specifications on every step of the eBook format.

While it is possible to create a compliant ePub file using merely a text editor and a program to make zip files, and while creating a small book that way may be useful as a learning exercise, large-scale content creation would be tedious and error prone. (For those interested in trying, a tutorial is available at http://www.jedisaber.com/eBooks/tutorial.asp.) There are a number of tools that can help with the creation of ePub files. First off is Stanza Desktop: while Stanza iPhone/iPod only supports ePub files, Stanza Desktop is able to read books in a number of formats (such as Mobipocket, MS Word, PDF, HTML, Plain text, RTF, Fictionbook, and many others) and can export them to fully-compliant Open eBook files. Although this is a good solution if you are interested in the quick (and, while Stanza is still in beta, free) conversion of your content to Open eBook, it does present some limitations, since Stanza Desktop is primarily a reading platform, not a full transcoding platform. As such, many elements of a book, such as formatting, tables, and images, are lost when Stanza opens and converts the book content to Open eBook. These limitations can be unacceptable to some book publishers and distributors.

If you already have your books in HTML format, you can also try using the online book conversion tool at http://www.bookglutton.com/api to convert your files to ePub.

For publishers and distributors who want more sophisticated control over the generation of ePub files than Stanza Desktop can provide, Adobe InDesign is able to generate ePub content directly. InDesign is not cheap, but they do have a free trial available. Instructions for using InDesign to create ePub files can be found at http://blogs.adobe.com/digitaleditions/indesign-epub.html.

Finally, for the XML-oriented developer, docbook files can be transformed into compliant ePub files using a recent release of the docbook XSL style sheets. (Read about it here.) Docbook is a widely-used XML format to express the complete contents of a book. Contrary to what the name suggests, it is not limited to just documentation, but can support any book contents. This options is attractive to developers who might already have their content in some other XML format (such as Fictionbook files); an experienced developer can assemble a toolchain to transform their content into docbook and then use the standard style sheets to generate the resulting ePub, in a completely automated way.

Once you have created or converted your book into the ePub format through whichever mechanism you like, you must ensure that the file is fully compliant with the ePub standard. Stanza will not open the ePub file unless it is 100% compliant with the standard. Fortunately, there is a very useful free tool available to validate that your generated content complies with the ePub standard: http://code.google.com/p/epubcheck/.

The Catalog Format: XML

So you've transformed your thousands of free books into 100% compliant Open eBook ePub files, and now you want to create your own catalog that Stanza will access to read your books. Stanza uses the standard Atom protocol for catalogs. A good description of Atom can be found at Wikipedia, and the full specification is described in RFC 4287 – "The Atom Syndication Format".

The catalog is defined as a series of links. The only two mime types that Stanza supports are "application/atom+xml" (which specified that the link goes to another catalog file, which allows for the creation of hierarchical catalogs), and "application/epub+zip", which specifies that the link points to a valid ePub book. When composing Atom files by hand, it is strongly recommended that you utilize a validator to ensure that the file will be compatible with Stanza, such as the one at http://validator.w3.org/feed.

Following is an example of how a top-level catalog (which just points to other catalogs) might look:

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Billy Bob's Book Catalog</title>
  <updated>2008-08-18T17:40:58-07:00</updated>
  <author>
    <name>Billy Bob</name>
    <uri>http://www.billybobsbooks.com/</uri>
    <email>billybob@billybobsbooks.com</email>
  </author>
  <subtitle>
        Online catalog of Billy Bob's Booka!
    </subtitle>
  <id>urn:uuid:60a76c80-d399-12d9-b91C-0883939e0af6</id>
  <link rel="self" type="application/atom+xml" href="http://www.example.com/catalog.atom"/>
  <entry>
    <title>Some Good Books</title>
    <id>urn:uuid:1925c615-cab8-4ebb-aaaa-81da314efc61</id>
    <updated>2008-08-18T17:40:59-07:00</updated>
    <link type="application/atom+xml" href="goodbooks.atom"/>
  </entry>
  <entry>
    <title>Short Reads</title>
    <id>urn:uuid:1925c615-cab8-4ebb-aaaa-81da314efc62</id>
    <updated>2008-08-18T17:41:00-07:00</updated>
    <link type="application/atom+xml" href="shortreads.atom"/>
  </entry>
  <entry>
    <title>Classics &amp; Epics</title>
    <id>urn:uuid:1925c615-cab8-4ebb-aaaa-81da314efc63</id>
    <updated>2008-08-18T17:41:01-07:00</updated>
    <link type="application/atom+xml" href="classicsepics.atom"/>
  </entry>
</feed>

To link to the actual books in your catalog, your link tags must be of the type "application/epub+zip". An example catalog is as follows:

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <title>Online Catalog</title>
  <id>urn:uuid:09aeccc1-c633-aa48-22ab-000052cbd81c</id>
  <updated>2008-09-12T00:44:20+00:00</updated>
  <link rel="self" type="application/atom+xml" href="http://www.billybobsbooks.com/catalog/top.atom"/>
  <link rel="search" title="Search Billy Bob's Books" type="application/atom+xml" href="http://www.billybobsbooks.com/catalog/search.php?search={searchTerms}"/>
  <author>
    <name>Billy Bob</name>
    <uri>http://www.billybobsbooks.com</uri>
    <email>billybob@billybobsbooks.com</email>
  </author>
  <entry>
    <title>1984</title>
    <content type="xhtml">
      <div xmlns="http://www.w3.org/1999/xhtml"> Published: 1949 Subject: Novels Language: en</div>
    </content>
    <id>urn:billybobsbooks:1166</id>
    <author>
      <name>Orwell, George</name>
    </author>
    <updated>2008-09-12T00:44:20+00:00</updated>
    <link type="application/epub+zip" href="http://www.billybobsbooks.com/book/1984.epub"/>
    <link rel="x-stanza-cover-image-thumbnail" type="image/png" href="http://www.billybobsbooks.com/book/1984.png"/>
    <link rel="x-stanza-cover-image" type="image/png" href="http://www.billybobsbooks.com/book/1984.png"/>
  </entry>
  <entry>
    <title>The Art of War</title>
    <content type="xhtml">
      <div xmlns="http://www.w3.org/1999/xhtml">Published: -500 Subject: Non-Fiction Language: en</div>
    </content>
    <id>urn:billybobsbooks:168</id>
    <author>
      <name>Sun Tzu</name>
    </author>
    <updated>2008-09-12T00:44:20+00:00</updated>
    <link type="application/epub+zip" href="http://www.billybobsbooks.com/book/artofwar.epub"/>
    <link rel="x-stanza-cover-image-thumbnail" type="image/png" href="http://www.billybobsbooks.com/book/artofwar.png"/>
    <link rel="x-stanza-cover-image" type="image/png" href="http://www.billybobsbooks.com/book/artofwar.png"/>
  </entry>
</feed>

Note: For large and complex catalogs, you may be interested in dynamically generating the catalog XML files. Stanza makes no distinction between catalogs that are kept statically or dynamically.

Other catalog features

The Stanza catalog format also had the following additional features:

Searching

If you have a link with the rel search in the header of any Atom XML file, Stanza will show a magnifying glass icon in the upper-right corner of the catalog interface. The user will then be able to enter search terms into the search box that pops up, and it will be sent to the server by replacing the instance of the string "{searchTerms}" in the link's href attribute.

For example, if you have the following link:

<link rel="search" title="Search Catalog" type="application/atom+xml" href="http://www.billybobsbooks.com/search.php?q={searchTerms}"/>

Stanza does not put any requirements on the search terms you enter or the meaning of the search. For example, if your top-level catalog has an "Authors" sub-catalog, you could have the search URL that comes up in that catalog prioritize author names. Alternatively, you could have all your search URLs always go to a single global search URL (which is the decision that most catalogs choose).

Embedded Browser

Stanza handles links of type application/atom+xml by loading the results as another catalog entry, and handles links of type application/epub+zip and application/ereader by loading the URL and trying to import it as a book. Additionally, you can have links of type application/xhtml+xml and text/html from your catalog entry, which will cause Stanza to push an embedded web browser as the next view. The embedded browser uses the same rendering engine ("WebKit") as Safari does, and in general it behaves similarly to Safari. It does not have all the features of a full browser (specifically, it lacks bookmarks, the ability to open links in a new window, history searching, or the ability to enter an arbitrary URL), but it is sufficient to perform most browsing activities. The embedded browser also has one feature that Safari on the iPhone lacks: it is able to download ePub and eReader books directly from a web page. So if you have a storefront where people can download books, and the user loads that web page from within Stanza's embedded browser, the user will be able to download those books directly into Stanza.

One way in which the embedded browser is frequently used is as a mechanism for the user to register an account with a bookstore, or to perform the purchase transaction (as Stanza does not yet have any built-in transaction processing abilities). A book store's catalog may allow users to browse and search for books using the familiar and efficient Stanza catalog Atom XML interface, but then when they want to purchase and download the book, they might enter the embedded browser to log in and complete the transaction. Another way in which the embedded browser feature is used is to provide links to other sites that might have additional useful information like book reviews.

Catalog Description Page

It is generally recommended that the first entry in your top-level of a catalog has an "About" link to an XHTML page describing the catalog, its contents, and contact information for the catalog maintainer. This can be accomplished by having a normal entry that links to an XHTML page with that information. E.g.:

<entry>
<title>About this Catalog</title>
<link type="text/html" href="about.xhtml"></link>
<content type="text">About Billy Bob's Books</content>
</entry>
<entry>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="viewport" content="initial-scale=1.0, user-scalable=no" />
<meta name="stanza-toolbars" content="hide" />
<link href="http://images.lexcycle.com/mobiletext.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="title">Information about Billy Bob's Book</div>
<div id="description">
<hr/>
<p>
Welcome to Billy Bob's Books! We aim to be your one-stop shop for all books related to fans of Billy Bob!
</p>

<h3>How to suggest books</h3>
<p>
If you have any books you would like to suggest for this catalog, please contact
Billy Bob himself at <a href="mailto:billybob@billybobsbooks.com">billybob@billybobsbooks.com</a> ...
</p>
</div>
</body>
</html>

Authentication

Stanza's catalog supports basic HTTP authentication, which you can use to provide catalog information specific to the user. If a "401 Unauthorized" code is sent back for any requests, then Stanza will pop-up a username/password dialog which enabled the user to enter a username and password. This information is useful if, say, your catalog has a "bookshelf" feature that can list all the books that a user has purchased.

Links in Book Descriptions

A book description can contain one or more link elements, which will be displayed beneath the book's description in the catalog. The rel for these links is not currently used, but the links to need to be of a supported type. I.e., they need to be one of:

• application/atom+xml: traverses to the specified catalog
• application/epub+zip: downloads the specified link and imports the book
• application/ereader: downloads the specified link and imports the book
• application/xhtml+xml: launches the embedded browser with the URL
• text/html: launches the embedded browser with the URL

Having links in the book description is essential for providing the ability for the user to perform additional actions for the book. For example, the book may have an application/xhtml+xml link that goes to a web page that contains book reviews, an application/atom+xml that links to a "People Also Purchases..." catalog of similar books, and a application/epub+zip link that allows the user to download a free sample of the book.

Results Pagination

Since users may be on slow cellular networks when accessing your catalog, you should avoid sending very large batches of responses to any requests. In general, we recommend paginating results in batches of 20 or 30. If a catalog has a link with rel='next', then that will cause Stanza to display a "Load More Results..." button at the bottom of the catalog. When clicked, the URL in the link will be hit, and additional results will be loaded and appended to the current catalog list.

Catalog Subdescriptions

Sub-catalogs can have a small piece of descriptive text that appears below the catalog name. This is useful for summarizing the catalog contents or providing additional hints. This is accomplished by using code like:

<entry>
  <title>Andersen, Hans Christian</title>
  <link type="application/atom+xml" href="http://www.billybobsbooks.com/anderson.atom"></link>
  <content type="text">11 books by this author</content>
</entry>

Compression

Stanza supports gzip compression for all catalog interactions. It is highly recommended that you enable this feature on your web server, as it can dramatically speed up catalog access, especially for people using Stanza over slow cellular networks.

Icons

Catalog developers are encourages to use icons for book descriptions as well as catalog and sub-catalog entries. Links will a rel of x-stanza-cover-image-thumbnail will be displayed in the catalog list, and links with a rel of x-stanza-cover-image will show up as the cover image when the user taps on the book's listing to get its description. The thumbnail image for a book should have a maximum width & height of 125 pixels. There are no restrictions on the aspect ratio of the image, but in general it is recommended that you try to be consistent in the aspect ratio for your books. We generally recommend an aspect ratio of 2:3 (width:height). If a thumbnail image has a width or height greater than 125 pixels, Stanza will scale it down and preserve the aspect ratio. However, since users may open a large list of books, it is essential you make efficient use of bandwidth by keeping the size of the images as small as possible.

In addition to thumbnail and full sized cover images, Stanza also supports images attached to sub-catalogs. This, in combination with using catalog sub-descriptions, can provide a useful hint to the user about the meaning of a particular catalog entry. As with cover images, there are no restrictions on the particular size of a catalog icon, but care should be taken to keep the image size as small as possible, and to keep the size consistent across all entries in the catalog.

When the href attribute of an image or icon is a URL, Stanza will asynchronously fetch that URL whenever the book is displayed. This makes efficient use of bandwidth, since if a user brings up a catalog page with 25 books, only the first books that are displayed will have their covers automatically fetched. As the user scrolls down the list, the covers will dynamically be fetched for those books (provided they are not already cached). In some cases, however, it might make more sense to pre-load the image by embedded it directly into the catalog page. This might be used for, say, the top-level view of the catalog where you will always have the same icons for the page. In these cases, you can instead use a URL of the form "data:image/png;base64,..." to embed the Base-64 encoded image data directly into the XML, thereby removing the need for Stanza to asynchronously request the image. A good description of the Data URL scheme, as well as links to tools that can generate a data: URI for your images, can be found at Wikipedia.

The Catalog Transport: HTTP

The last step of making your content available online is hosting it. Stanza accesses catalogs via standard HTTP; that is, you need to host your catalogs and books on a web server. Setting up a web server or hosting options is well beyond the scope of this documentation, but in short, if you are able to create and upload a web page so it is available on the internet, you are able to create a public catalog that Stanza can use. There are a wide variety of Atom publishing tools available, most of which we expect to be compatible with Stanza. You may wish to investigate using some of these tools to create catalogs.

Testing your catalog

Once you have created your books, generated or written your catalog files, and set them all up on a host somewhere, you can now test your catalog! In Stanza 1.5, you can add a new catalog by going to the "Online Catalog" section and tapping the "+" button, where you can enter the name and URL of you catalog to add.

The Final Steps

You can use a link formatted with the "stanzacatalog://" protocol, which, when accessed on an iPhone or iPod that already has Stanza 1.5 or higher installed, will launch Stanza and add the linked catalog as a new custom catalog. For example, if your catalog located at "http://www.billybobsbooks.com/catalog.atom", accessing a link of the format "stanzacatalog://www.billybobsbooks.com/catalog.atom" will result in that catalog being added to your Stanza catalog.

Lexcycle also provides the ability for some catalogs to be listed in Stanza's default Online Catalog section. Please contact catalog@lexcycle.com for further details.

Catalog Checklist

Here are some final checklists for ensuring that your catalog provides a good user experience:

1. Does your catalog's Atom XML pass the validator at http://validator.w3.org/feed? If not, then people will probably encounter problems with your catalog.
2. If your catalog is a "large" catalog (i.e., more than 100 books), do you provide a "search" feature?
3. If your catalog is large, do you sub-divide the catalog into logical sections (such as books by author, genre, title, etc.)?
4. When your catalog displays a large number of books, do you paginate the results?
5. Do you have an "About" page describing the catalog at the top of the first catalog page the user sees?
6. Do you include cover art (both thumbnails and large versions) for your books? Users love cover art.
7. Do your book entries include comprehensive descriptions of the books?