Frequently Asked Questions

This FAQ provides basic information and links to other resources.

General

Where is Atlas content hosted?

Source HTMLBook, images, and other project assets are stored on an O'Reilly-managed git server hosted on Amazon's cloud infrastructure. Rendered output formats (PDFs, EPUB, MOBI, and HTML) are stored and archived on Amazon's cloud infrastructure. Each project is only accessible to users who have specifically been granted access, and each rendition of the content is only accessible by a user authorized to access the project.

Atlas is hosted on the Amazon AWS cloud. AWS has in the past successfully completed multiple SAS70 Type II audits, and now publishes a Service Organization Controls 1 (SOC 1), Type 2 report, published under both the SSAE 16 and the ISAE 3402 professional standards as well as a Service Organization Controls 2 (SOC 2) report. In addition, AWS has achieved ISO 27001 certification. More information is available at Amazon's AWS Compliance page.

Is Atlas content backed up?

Atlas and its data stores are backed up with offsite storage. In addition, Atlas is monitored 24/7 to help ensure the highest level of availability and early detection of any potential issues.

As a general best practice, we encourage users to keep local and backed-up copies of both source files and rendered formats in a system controlled by the user.

How is access control handled?

There are both organization and project-level permissions. Anyone within your organization who will need access to all projects created may be added to your organizational account. There is no limit to the number of users that may be added at the organization level.

Anyone needing access to a specific project would be added to that particular project under the Settings tab for that project. A collaborator on a given project is able to invite others into the same project.

Can I export files directly from Atlas into another CMS?

It is very simple via our API to export files from the system. You can use standard Git operations to pull source files directly from Atlas, and you can trigger generation of and download ebook files via the Atlas RESTful API.

The Atlas API does not currently provide any handling for posting files to other CMSes, so automation for loading files to other systems would be something that you would need to take care of on your own.

Can I set up automated notifications to alert collaborators?

We've been asked this question by a number of users, which suggests to us that it's a ripe area for building out new features to the tool, especially as we elaborate on our collaboration suite. But at present, users must manually coordinate to manage the workflow and keep projects on track.

What kind of reporting is available?

There is currently no reporting dashboard in Atlas. We are working on improving the management reporting that was available in our previous version of Atlas and bringing it to the current version of Atlas.

If you’d like to explore some of what’s available on your own, you can take a look at the gitstats program that works on a local copy of the project.

I'd like O'Reilly to create a custom template for my projects. What do I need to know?

We offer template creation as a professional service. We would want to have copies of the source files and output formats from the series/design you’d like to create, and we’ll build out from those samples. The cost is variable. Once the design is done for a series, it can be leveraged again and again for rendering formats across all projects in that series.

Writing and Editing

Why are some "Insert" options unavailable?

The Atlas Visual Editor was designed to ensure that when users author and edit content in the editor, the output will be valid HTMLBook. Options for content insertion are driven by the HTMLBook schema (available in GitHub at https://github.com/oreillymedia/HTMLBook/blob/master/schema/htmlbook.xsd).

As an example, the Atlas editor will allow you to embed a sidebar within chapter content, but will not allow you to embed another chapter within a chapter, as the latter is not supported in the HTMLBook spec and will not validate against the HTMLBook schema.

Do images need to be sized before ingestion?

The CSS templates that drive the look and feel of the output include handling that limits the width of images to certain maximum sizes, depending on where they appear in the text. For example, the CSS may allow a maximum image width of, say, 4 inches in the body text, but only 3 inches if the figure appears inside a sidebar element.

How can I upload multiple images at once?

Right now, batch loading a large number of assets (e.g., a folder full of images) is not supported via the Web interface. Your best bet for doing so would be to use Git to load the files from a local checkout.

Can I lock files or projects for use by a specific collaborator?

No, we’ve opted not to implement a locking system in Atlas, in which only one person can work on a document at a time. Instead, we’re implementing a “branch” model, in which each collaborator on a project has his or her own separate copy of all files in the project that can be worked on independently of all other users.

When you're ready to merge your changes into the canonical “master” copy of the content, you can submit a “merge request.” The person responsible for managing changes will see a side-by-side comparison of changes made in the collaborator’s personal branch vs. the master copy, and Atlas will allow him or her to accept and reject changes, as in Microsoft Word’s track-changes feature.

These new Atlas collaboration features will be released incrementally over the next few months.

How do I number elements like tables, figures, etc.?

Numbering of formal elements—such as tables, figures, and listings—is automatic and built right into the Atlas toolchain. The numbering can be customized as needed in different book templates by tweaks to CSS; it’s easy to turn on or off auto-numbering as needed for any element, and customize the numbering style per the conventions in a given template.

How does Atlas handle metadata?

Atlas currently supports embedding of metadata in HTML content using the <meta> tag. You can see an example in the HTMLBook documentation here.

In addition, we are planning a UI update that will allow users to enter metadata like ISBN, price, marketing description, etc. directly from the project dashboard.

Does Atlas support interactive elements?

Yes! Because the source format of Atlas is HTML5, you can directly embed any multimedia/interactive features you wish that make use of HTML/CSS/JavaScript technology, or use the <iframe> element to pull in content from other web sites. For some examples of interactive elements in book content, you may want to take a look at O'Reilly's HTML5 for Publishers book, which contains some fun examples, including an SVG-based coloring book and an interactive quadratic equation solver.

The one caveat about interactive elements in ebooks is that they are contingent on support being available in ereader devices and apps. So, for example, while Apple’s iBooks reader provides support for JavaScript in EPUB, other ereaders do not. Our solution for this in Atlas is that we provide the opportunity to designate “fallback content” for display when interactive/multimedia capabilities are not available. So in the case of embedded video, you can supply a fallback image and/or URL that points to the video on the web, which can be displayed in lieu of the video content in the print book or on ereaders (such as eInk devices) that do not support video.

Why can't I edit the files in my project?

If you've been invited to someone's project as a collaborator, you must make your own branch of the project to work in. Simply click "Add a branch" from the project dashboard, and you'll create your own workspace within the project. After you've made some changes, you can submit your changes for review by one of the project owners. If they're approved, they'll be merged into the master version of the project.

You can read more about the branches workflow in Atlas and how to use the collaboration features here.

File Creation

Are there any built-in validation mechanisms?

EPUB validation (against epubcheck 3) is built directly into the Atlas system via the “Run epubcheck” option on the Configure page. EPUB validation Results can be reviewed in the build log.

Is pagination info included in EPUB files?

The EPUB 3 files generated by Atlas are standard reflowable EPUBs, which means they have no set pagination. At this time, Atlas does not support generation of fixed-layout EPUBs, nor does it support generation of the page-list <nav> element for mapping content in PDF output by page number to corresponding content in EPUB output.

You may configure pagebreaks in EPUB using CSS's page-break properties, though these properties are not supported in all ereaders.

How is EPUB navigation generated?

The navigation information needed for EPUB 3 files (e.g., the OPF spine, the EPUB Navigation Document, and the NCX TOC for EPUB 2 backward compatibility) is auto-generated by the Atlas toolchain. However, the manifest in the Files to Build section is not directly translated into the EPUB's spine. Instead, Atlas consolidates the content and rechunks the HTML into content documents at the size defined by the Atlas user.

By default, Atlas will chunk EPUB content at the chapter level (i.e., each chapter/preface/appendix in the book content will be a separate content document in the EPUB archive). But users can tweak this setting to specify that each subsection ("sect1"), sub-subsection ("sect2"), etc., be a separate chunk if they prefer.

What happens when ebook specifications are updated?

As ebook specifications and ereader platforms continue to evolve (e.g., the newly proposed updates to the EPUB 3 specification in EPUB 3.0.1; future updates to the iBooks software), we will make updates to Atlas’s ebook-generation toolchains to ensure that outputs are compatible with the latest-and-greatest specifications and ereaders. This means that updating ebook files to the latest specs will be as simple as pushing the Build button in the Atlas UI.

Can I embed my preferred fonts in EPUB and Mobi files?

As part of the Atlas workflow, there are 4 font families that are automatically embedded in the ePub/Mobi files:

  • DejaVu Sans Bold: Open source Sans Serif font for headers/titles
  • DejaVu Serif: Open source Serif font for general text
  • UbuntuMono: Open Source Monospace font for code
  • Arial Unicode: A backup font used to cover unusual glyphs not included in the other font sets

These fonts have been vetted and cleared for use in digital books without restriction.

While it is possible to embed additional custom fonts, we don't recommend it for the following reasons:

  • Any embedded fonts must be either Open Source or specifically licensed for use in digital books.
  • Any embedded fonts must be TT (True Type) or OTF (Open Type) and specifically built to include the necessary data to be useable in a digital book.
  • Many licensed fonts require an additional fee for use in digital books.
  • Many licensed fonts require that only a subset of the font be used in digital books, and that they also be obfuscated and encrypted.
  • Many eBook readers/devices do not support embedded fonts at this time.
  • eBook readers/devices allow users to control how content is displayed, including the ability to change the display font at any time (even if it is embedded)

For more information about the pros and cons of EPUB and Mobi font embedding, see chapter 4 of EPUB3 Best Practices (O'Reilly, 2013).

If you'd still like to embed additional fonts in your EPUB and Mobi files, please contact us so that we can help advise on the best way forward.

Ownership and Distribution

Do I own my content?

Absolutely. You retain full copyright to your content, and you can easily export all of the files in your project from the Project Settings screen. Also, because Atlas uses HTML instead of a proprietary format, you're never locked in to the platform.

Where can I sell and distribute my content?

Atlas generates all three of the standard ebook formats: EPUB, MOBI (for Kindle), and PDF, and files can be distributed to all major digital retailers, including Amazon Kindle Store, Apple iBooks, Barnes & Noble, Google Play, etc. Just build with Atlas, download the output, and distribute and sell wherever you see fit!