"a book publishing framework for today's publishing world"
bookshop is a book publishing framework for publishers, editors, and coders in today’s publishing industry. bookshop provides a framework for developing books using well-known/standard web languages like HTML/CSS, which are then converted into pdf and other (e)book formats. The framework is optimized to help developers quickly ramp-up, allowing them to jump in and develop their html-to-pdf/(e)book flows, by favoring convention over configuration, setting them up with best-practices, standards and tools from the start.
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
-
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 (wkhtmltopdf, kindlegen, epubcheck)
-
sticking with open-source tools to encourage community development
-
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)
-
Ruby v1.8.7 or higher www.ruby-lang.org/en/downloads/
$ gem install bookshop
-
Try using the wkhtmltopdf-binary gem (mac + linux i386)
$ gem install wkhtmltopdf-binary
-
Install by hand (for windows or users who want to install newer builds):
github.com/blueheadpublishing/bookshop/wiki/Installing-wkhtmltopdf
-
The wkhtmltopdf site has more info
http://code.google.com/p/wkhtmltopdf/
$ bookshop new my_new_book
This will create a new bookshop book in /path/to/my_new_book with the following structure:
|-- book/ # Source files for your book
|--book.html.erb # The master file
|--css/
|--stylesheet.css
|--images/
|-- builds/ # All the builds are created here
|--epub/
|--html/
|--mobi/
|--pdf/
|-- config/ # Your config and data settings
|--book.yml # Settings/Data for your book
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).
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
Your master file (which is used to build everything) 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…
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
You can also create sub-folders and group your files there. For example, in your book.html.erb file you could import:
<%= import('ch1/my_first_section.html.erb') %>
This would import the file book/ch1/my_first_section.html.erb
Note that you can also nest import files into imported files.
So in your book/book.html.erb
<%= import('ch01/ch01.html.erb') %>
and in the ch01/ch01.html.erb you could import more files
<%= import('first_section.html.erb') %>
<%= import('second_section.html.erb') %>
So what if you want to create content for certain builds only? Let’s say you want to have a different title for the pdf then you do for the epub version of the 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 titles that change depending on the build, using a conditional statement (remember, everything is ERB, so we can use Ruby):
<p>
<% if @output == :html %>
HTML Title
<% elsif @output == :pdf %>
PDF Title
<% elsif @output == :epub %>
EPUB Title
<% end %>
</p>
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 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 %>
More info about YAML:
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).
To build an HTML format of your book from the ERB source:
$ bookshop build html # -> find the output in builds/html/book_(date).html
To build a pdf format of your book from the ERB source:
$ bookshop build pdf # -> find the output in builds/pdf/book_(date).pdf
What if you want your pdf to print as Lanscape, or a different page-size, or in grayscale? Because bookshop uses PDFKit, you can pass wkhtmltopdf (the pdf rendering engine) options by way of <meta> tags in your html source code.
For example, to print in Landscape mode, in your master book/book.html.erb file we can add <meta name=“pdfkit-orientation” content=“Landscape” />:
so you html would be:
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1" />
<meta name="pdfkit-orientation" content="Landscape" />
<title>how-to bookshop</title>
<link rel="stylesheet" type="text/css" href="css/stylesheet.css" />
</head>
<body>
<p>The ISBN is <%= @book.isbn %></p>
Here’s a list of other options github.com/blueheadpublishing/bookshop/wiki/wkhtmltopdf-options
Or you can look at all of the possible wkhtmltopdf options by using the command:
$ wkhtmltopdf --extended-help
Your meta tags should use the following naming conventions.
-
For each option, replace the double-dashes ‘–’ before the option with
pdfkit-and change single-dashes ‘-’ to an underscore_.--page-size becomes <meta name="pdfkit-page_size" content="Letter" />
-
For options that do not require an additional parameter/value, you still need to include the content attribute, but keep it blank.
--grayscale becomes <meta name="pdfkit-grayscale" content="" />
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.
The default directory structure of a generated bookshop project:
|-- book/ # Source files for your book
|--book.html.erb # The master file
|--css/
|--stylesheet.css
|--images/
|-- 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
-
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!!
Copyright © 2010, 2011 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.
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
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 WKHTMLTOPDF team code.google.com/p/wkhtmltopdf/