File: README — Documentation for bookshop (0.1.8)

Bookshop is a an open-source agile book development and publishing framework for authors, editors, publishers and coders in today’s publishing industry. Bookshop provides best-practices for developing your books in HTML/CSS/JS, allowing them to be transformed into potentially any book format (Print-PDF, Online-PDF, mobi, ePub, etc.).

A conceptual overview of bookshop: blueheadblog.blogspot.com/2012/03/announcing-bookshop-html-to-pdf-ebook.html

bookshop hopes to simplify the book publishing toolchain by:

using industry standards tools like HTML5, CSS, and JS to make the creation of your book comfortable and familiar, greatly reducing the learning curve for your developers, authors, agents, and other team members
separating the “book” into its logical parts:
- Content via HTML5 (the actual words, grammar, tense, etc.)
- Structure via Boom! Microformat (chapters, sections, dedication, preface, etc.)
- Style via CSS3 and JS (layout, design, typeset)
- Format (pdf, mobi, epub, html)
providing a Ruby Gem to make the building of your book as easy as _gem install bookshop_
pulling all the publishing tools together into one place (princexml, kindlegen, epubcheck)
giving the developer a set of scripts to automate the redundant stuff
providing an architecture/structure that follows best-practices and simplification (DRY… Don’t Repeat Yourself)

Getting Started

System Requirements

Ruby v1.8.7 or higher www.ruby-lang.org/en/downloads/
Java 1.5 or higher www.java.com/en/

Installation

For detailed installation instructions for your particular platform, please see this link:

github.com/blueheadpublishing/bookshop/wiki/Setting-Up-Your-bookshop-Environment

Install bookshop

$ gem install bookshop

Install PrinceXML

Go to PrinceXML website and follow the install instructions

www.princexml.com/download

Using bookshop

Create a bookshop book

$ bookshop new my_new_book

This will create a new bookshop book project in /path/to/my_new_book with the following structure:

|-- book/                 # Source files for your book
    |--book.html.erb      # The master file
    |--frontmatter/       # Content at the front of the book (cover, title, preface, etc.)
    |--bodymatter/        # Main content of book (chapters, sections, etc.)
    |--backmatter/        # Content at the back of the book (appendix, index, etc.)
    |--assets/
        |--css/
            |--stylesheet.pdf.css
        |--images/
        |--js/
    |--epub/              # epub specific files and contents
        |--META-INF/
        |--mimetype
        |--OEBPS/
            |--content.opf.erb
            |--toc.ncx.erb

|-- builds/               # All the builds are created here
    |--epub/
    |--html/
    |--mobi/
    |--pdf/

|-- config/               # Your config and data settings
    |--book.yml           # Settings/Data for your book

Editing Your New Book

Editing your book source

Currently, when you create a new bookshop project, it will generate the example book source for you. You can use this as a template, replacing the text with your own. But make sure to utilize the correct CSS microformat markup.

For an explanation of the example, please see this article. - www.alistapart.com/articles/boom

All of the source documents and assets for your book are stored in the book/ folder. So your stylesheets, images, text - everything used for building your book - lives here. Ideally, you should only every edit files in your book/ folder (with the exception of your config/book.yml file).

Why do the Source files end with `.erb`?

The source files are all in ERB. ERB is a templating language for the Ruby programming language. Why is this cool? Because it means that you can use HTML and you can embed Ruby code in your source files. In other words, you can do all kinds of cool programmy things. Like embed ruby functions and calls:

<p>Today is <%= Time.now.strftime('%A') %>.</p>  # creates -> <p>Today is Thursday.</p>

More information on ERB - www.ruby-doc.org/stdlib-1.9.3/libdoc/erb/rdoc/ERB.html

The master file book.html.erb

Your master file (from which everything is built) is the book.html.erb file (remember that we are in the book/ folder). You could of course just use this file and put all of your book contents here, making one enormous file, but we don’t recommend it…

Import files into your master file

Are you writing another “War and Peace”? We’ve created a nice way to make your epic book easier to manage. Rather than putting everything in the book.html.erb file, you can import files. This allows you to break your book up into smaller, more manageable pieces. This makes it soooooo much easier to manage your book. And others will thank you for it..

You can import a file by using the import() function, for example:

<%= import('a_whole_chapter.html.erb') %>

This would import the file book/a_whole_chapter.html.erb

You can also create sub-folders and group your files there. For example, in your book.html.erb file you could import:

<%= import('bodymatter/ch01/my_first_section.html.erb') %>

This would import the file book/bodymatter/ch01/my_first_section.html.erb

Note that you can also nest import files into imported files.

So in your book/book.html.erb

<%= import('bodymatter/ch01/ch01.html.erb') %>

and in the bodymatter/ch01/ch01.html.erb you could import more files

<%= import('bodymatter/ch01/first_section.html.erb') %>
<%= import('bodymatter/ch01/second_section.html.erb') %>

Use the @output tag to create content based on output (pdf/html/epub/etc.)

So what if you want to create content for certain builds only? Let’s say you want a certain section of your book to only be included in the pdf version of your book.

No worries. We’ve created the handy Output Variable (@output) for you to use in this case… aren’t we special?

Currently we have three attributes you can call with @output - :html, :pdf, and :epub.

Let’s generate a section that will only be displayed in the pdf version of your book, using a conditional statement (remember, everything is ERB, so we can use Ruby):

<% if @output == :pdf %>
  <p>This is a pdf-only section</p>
<% end %>

Use @book tags to reuse content throughout all book formats (the `config/book.yml` file)

Gosh, wouldn’t it be cool to have a way to store bits of information that we use repeatedly throughout the book, like the ISBN, or the title? And then it would be great to be able to reference them from within the book source. That way we can change them once, in one place, rather than having to go looking for them throughout the entire book.

We’ve provided a data structure for your book (in YAML) so you can store these pieces of data in variables that you can call within your source files.

Here’s an example config/book.yml file with some Book Variables:

# book.yml

isbn: 1234567891011

html:
  title: An HTML Title

pdf:
  title: A PDF Title
  pub_date: 12/13/2012

epub:
  title: A EPUB Title
  pub_date: 11/13/2012

You can then use these Book Variables in your book source file:

<p>The book isbn is <%= @book.isbn %></p>
<p>The html title is <%= @book.html.title %></p>
<p>The epub pub_date is <%= @book.epub.pub_date %></p>

Note that you can also construct and/or nest variables however you want to:

# book.yml

my:
  madeup:
    friend:
      name: dave

Then call it in your source file with the variable:

<p>My made up friend's name is <%= @book.my.madeup.friend.name %></p>

More info about YAML:

en.wikipedia.org/wiki/YAML

Mixing it up

So, do you want to see something cool? Now that we have the Output Variable and Book Variables, we can combine them to do nifty things, like:

<p>The ISBN is <%= @book.isbn %></p>
<p>Title: 
  <% if @output == :html %>
    <%= @book.html.title %>
  <% elsif @output == :pdf %>
    <%= @book.pdf.title %>
  <% elsif @output == :epub %>
    <%= @book.epub.title %>
  <% end %>
</p>

Please explore other creative ways to structure and enhance your book (we’d love to see how you are doing it).

Building Your First Book

Each time you build a new book format, the source .erb files in your book/ folder are built and copied to the build target folder. Then the final book format is generated from those newly generated files. For example, if you issue “bookshop build epub”, the .erb source files are built and the resulting book.html and all the assets/ are saved to the builds/epub/ folder. Then the target epub book format is generated from the builds/epub folder and saved back in the same folder.

The great thing about this is that you can easily view the resulting book.html file in a browser to get a quick peak at the generated look and feel.

To build an HTML format of your book from the ERB source:

$ bookshop build html   # -> find the output in builds/html/book.html

To build a pdf format of your book from the ERB source:

$ bookshop build pdf    # -> find the output in builds/pdf/book.pdf

To build an epub format of your book from the ERB source:

$ bookshop build epub    # -> find the output in builds/epub/book.pdf

Editing your pdf document options

We recommend consulting PrinceXML’s documentation concerning PDF options.

www.princexml.com/doc/8.0/

Editing you epub document and options

We decided to keep away from a generator model for the epub, in favor of allowing the developer to have full control of the epub file in all its aspects. The build command for epub is merely to build the main html file from the .erb source files and then to zip them up into the epub format.

There are two main files (besides your actual book source) you will need to edit for the epub build are located in the book/epub/OEBPS folder: content.opf (the Open Packaging Format) and the toc.ncx (the Navigation file).

1. The content.opf file is the file which contains all of the primary information about your epub ebook (publisher, files included, date, etc.).

idpf.org/epub/20/spec/OPF_2.0.1_draft.htm - Specs on the .opf file

idpf.org/epub/20/spec/OPF_2.0.1_draft.htm#Section2.4.1.2 - Specs on the .ncx file.

During the build process, the entire contents of the book/epub/ folder will be used, along with your book source files, to create your epub book format. You can add or edit any of the files in that folder if you like. Generally speaking, you will probably only ever edit the content.opf.erb and the toc.ncx.erb files.

idpf.org/epub/30 - For an overview of EPUB idpf.org/epub/30/spec/epub30-ocf.html - For the specs on the epub file structures and contents

We recommend consulting the EPUB documentation for specifics.

Example Book

We’ve provided an example book for you already in the book/ folder. You can use this as an example of how to structure your book and to use ERB, Book Variables, and Output Variables.

Simply create a new book:

bookshop new name_of_book

Then take a look at the example book in the book/ folder.

You can then build the book into whatever format you like.

Description of bookshop app contents

The default directory structure of a generated bookshop project:

|-- book/                 # Source files for your book
    |--book.html.erb      # The master file
    |--frontmatter/       # Content at the front of the book (cover, title, preface, etc.)
    |--bodymatter/        # Main content of book (chapters, sections, etc.)
    |--backmatter/        # Content at the back of the book (appendix, index, etc.)
    |--assets/
        |--css/
            |--stylesheet.css
        |--images/
        |--js/
    |--epub/              # epub specific files and contents
        |--META-INF/
        |--mimetype
        |--OEBPS/
            |--content.opf.erb
            |--toc.ncx.erb

|-- builds/               # All the builds are created here
    |--epub/
    |--html/
    |--mobi/
    |--pdf/

|-- config/               # Your config and data settings
    |--book.yml           # Settings/Data for your book

book

Holds all the manuscript html code/files. This is where your master manuscript lives from which everything is built.

builds

Holds all the output files built from the html

builds/epub

When building the epub, the generated output will reside here in an .epub file. You can rename the .epub extension to .zip then unzip the file to view the contents.

build/mobi

When building the mobi asset, the generated output will reside here as "book.mobi"

build/pdf

When building the pdf book, the generated output will reside here as "book.pdf"

config

application-wide variables and configurations will go here

Get Involved

Fork the repository.
Pick an issue (or feature you want to add).
Make changes to your forked code.
Add tests so that we don’t accidentally break your addition with our future commits.
Commit to your git (forked) repository.
Let us know about your code and we’ll review/merge it into the master.
And pat yourself on the back for contributing to an open source project!!

License

Bookshop is available under either The “New” BSD License or The MIT License

Please see the LICENSE file for further information

Thanks

We would like to thank:

The Ruby/Rubygems Team www.ruby-lang.org/
The Thor Team - github.com/wycats/thor
Hakon Wium Lie and Bert Bos for developing the book microformat www.alistapart.com/articles/boom
The PrinceXML Team - www.princexml.com/company/

A List of Our Contributors: github.com/blueheadpublishing/bookshop/blob/master/CONTRIBUTORS.md