Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

bookShop is a publishing framework for html-to-pdf/(e)book toolchain happiness and sustainable productivity.

This branch is 0 commits ahead and 0 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.rdoc

"a book publishing framework for today's publishing world"

Bookshop is a an open-source 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, 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 process by:

  • using common tools like HTML/CSS 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 HTML (words, grammar, tense), Structure via microformat (chapters, sections), Style via css (layout, design, typeset), and Format (pdf, mobi, epub, html)

  • providing a Ruby Gem to make building a book in HTML as easy as 'gem install bookshop'

  • pulling all the html-to-pdf/(e)book 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

(not required, but recommended for using other tools)

Installation

For detailed 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.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

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

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

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

The toc.ncx file is the file which contains the structural tree of your book's navigation.

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

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

  1. Fork the repository.

  2. Pick an issue (or feature you want to add).

  3. Make changes to your forked code.

  4. Add tests so that we don't accidentally break your addition with our future commits.

  5. Commit to your git (forked) repository.

  6. Let us know about your code and we'll review/merge it into the master.

  7. And pat yourself on the back for contributing to an open source project!!

Copyright (MIT-LICENSE)

Copyright (C) 2011, 2012 by BlueHead Publishing, Inc (blueheadpublishing.com)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The Boom Microformat License - boom.css (from which the css microformat was based)

www.alistapart.com/articles/boom

Sample style sheet for boom!, the book microformat
written  by Hakon Wium Lie and Bert Bos, November 2005
You may reuse this style sheet for any purpose without any fees

Thanks

We would like to thank:

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

Something went wrong with that request. Please try again.