-
Notifications
You must be signed in to change notification settings - Fork 23
Setting Up Your Bookshop Environment
This tutorial is meant to walk you through the basic setup of an environment for using bookshop on your specific platform.
There are a few options for installing Ruby. We recommend that you read the official Ruby site's instructions for installing Ruby on the your platform.
- For Windows users, we suggesting using the Ruby Installer. Here's a link to the exe http://rubyforge.org/frs/download.php/76054/rubyinstaller-1.9.3-p194.exe (Make sure to select "Add Ruby executables to your PATH" during install)
You may also consider using RVM (Ruby Version Manager), but this is a bit more advanced, for users who need to run different versions of Ruby. RVM only works on Mac and Linux.
Hopefully this is as simple as issuing the following from your command-line
$ gem install bookshop
- For Windows users, you can select "Start Command Prompt with Ruby" under the Ruby folder of your Startup menu.
Rubygems or "Gems" is a package distribution platform for Ruby (one of the main reasons we chose to make bookshop a gem). This allows us to set all of the dependencies of bookshop so that when you install it, everything magically happens for you. It's also cross platform.
If you have already installed Ruby, Rubygems should already be installed (it comes bundled with your Ruby installation). If your version of Ruby or Rubygems is older, you may need to go to your terminal's command-line and issue "gem update --system" to upgrade Rubygems, and then "gem update" to upgrade your local gems.
For the most part, you should be able to install bookshop from the command-line (terminal) by typing "gem install bookshop".
After the install finishes, you should see a message in your terminal that says:
Install PrinceXML: http://www.princexml.com/download/
- Windows users will need to make sure the prince.exe file is in their PATH (which can be edited in the Environmental Variables). The prince.exe command-line file (which bookshop uses) is located in the Prince\Engine\bin folder. This should not be confused with the GUI app Prince.exe in the main Prince install folder.
PrinceXML is the conversion tool that takes the HTML/CSS/JS and turns it into a PDF. Go to their download site for platform specific instructions on installing.
- Of note: PrinceXML is not open source, but they do provide a free license. In other words, you can use the downloaded software for free. The only caveat is that the generated pdf's will have a small logo stamp on the first page. Considering the feature-set of their product, we felt it was a fine tradeoff. If you want to generate a pdf without the logo stamp, you can either buy their license (a bit pricey) or use DocRaptor, which only charges a small monthly fee.
At this time we have not integrated bookshop into any particular text-editor. bookshop is strictly used via a terminal's command-line. You will need a text-editor to edit your book's code.
We tend to recommend Textmate for Mac users. It is not free, but it is one of the most well-used, especially within the Ruby community, which means you get a lot of great functionality and syntax highlighting.
For a free option you can use Aptana Studio which already comes with Ruby functionality. Or use Eclipse with the RadRails Plugin. Both of these work on any platform.
You can also use any basic web editor like Dreamweaver, Frontpage, Contribute, etc. Since your book is essentially just HTML/CSS/JS, they should all work. We recommend that you install your specific editor's Ruby package.
Generally speaking, when working on a book in bookshop, we find that we have the following workflow (applications in use):
- A Text Editor - where we can edit the book code and other configurations.
- A Command-Line Terminal - where we can issue bookshop commands like "bookshop build pdf"
- A Browser - where we can view the generate HTML or PDF
- Client platforms to test the final builds.