Frequently Asked Questions

This FAQ provides basic information and links to other resources.

General

How is access control handled?

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 set up automated notifications to alert collaborators?

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.

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.

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

As an example, the Atlas editor will allow you to embed a sidebar within chapter content, but it 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.

In addition, as part of the O’Reilly Production process, an Illustrator will resize all images to match the trim size of the project, so no resizing will be necessary.

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 that would ensure only one person can work on a document at a time. Instead, we’re leveraging Git’s support for branches, by which each collaborator on a project has their own separate copy of all files and can work independently of all other users.

When you’re ready to merge your changes into the canonical “main” copy of the content, you can use Git to accomplish this.

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

Numbering of formal elements—such as tables, figures, and code listings—is automatic and built right into the Atlas toolchain.

File Creation

Are there any built-in validation mechanisms?

Epub validation (against EPUBCheck) 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.

How is epub navigation generated?

The navigation information needed for EPUB 3 files (i.e., the OPF spine, the EPUB Navigation Document, and the NCX TOC for EPUB 2 backward compatibility) is autogenerated 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).

Can I embed my preferred fonts in epub files?

As part of the Atlas workflow, there are 4 font families that are automatically embedded in the ePub 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 font embedding, see Chapter 4 of EPUB 3 Best Practices (O’Reilly, 2013).