Skip to content

Latest commit

 

History

History
90 lines (63 loc) · 4.78 KB

ch02-getting-started.asc

File metadata and controls

90 lines (63 loc) · 4.78 KB
Raw

Getting Started

Command Overview

For those that already know the tools and just want to see the commands, here they are. If this makes no sense to you, don’t worry, all of this will be explained in greater detail in the next section of the User’s Guide. Once you are familiar with how Booksquisher works, you can come back to this section to remember the most important commands.

$ git clone --depth 1 --origin source https://github.com/mmarmor/booksquisher-example-book-templates.git new-book-project
$ docker pull marmor/booksquisher
$ docker run --name booksquish -it -v /<path-to>/new-book-project/:/documents/ marmor/booksquisher
[booksquisher]# cd /documents/book-template-1-simple
[booksquisher]# bundle install
[booksquisher]# bundle exec rake book:build

The generated books will be located in new-book-project/book-template-1-simple/generated-books on your local computer.

The Booksquisher Templates (but not the Pro Git 2 book) allow you to quickly remove the build artifacts and all the generated books with a clean command:

[booksquisher]# bundle exec rake book:clean

You can combine cleaning and building into a single command. This is the command you will use the most as you write your book and incrementally run a build to see how it looks:

[booksquisher]# bundle exec rake book:clean book:build

Exit and shut down the Docker container when you are done with Booksquisher for the day:

[booksquisher]# exit

The Docker container is still on your system, but no longer running:

$ docker container ls --all
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                    PORTS     NAMES
84eb14767b6e        booksquisher        "/bin/bash"         13 seconds ago      Exited (0) 9 seconds ago            booksquish

Re-start and attach to your container again. The same directory mapping you created before will still be ready to use:

$ docker start booksquish
$ docker attach booksquish
[booksquisher]#

Don’t want to use this container any more? Remove it like this:

$ docker container rm booksquish

The marmor/booksquisher Docker image is still on your system (even if you remove all the containers), so you can quickly make a new container from the image with the docker run command we used when we got started above:

$ docker images
REPOSITORY                       TAG                 IMAGE ID            CREATED             SIZE
marmor/booksquisher              latest              72ebe621b148        16 hours ago        531MB
$ docker run --name booksquish -it -v /<path-to>/booksquisher-example-book-templates/:/documents/ marmor/booksquisher

Get the latest version of the {booksquisher-docker-hub-image}:

$ docker pull marmor/booksquisher

Prerequisites

To use the Booksquisher Docker image, you’ll need Docker installed.

  • {docker-for-windows}

  • {docker-for-mac}

  • {docker-for-linux}

You should also have Git installed to get the Booksquisher example book templates (or the progit2 source) on your local machine.

  • {git-scm}

Note
A technical note about Git that you can safely ignore:
Note that Git is also included within the toolchain inside the Booksquisher Docker container. This is potentially confusing, so let me explain: The “internal” Git is used to pull the document version number which is included in the generated books. For this reason (and many others), it makes sense to use Git on your local machine when you work on your own book projects. The “internal” Git in the container is also used in the progit2 build script to fetch the most recent development version of asciidoctor-epub3, one of the critical tools for this build process—​and still in alpha—​from GitHub. The Docker image already contains an alpha-release version of asciidoctor-epub3 which you can use when building your own books, but the developers of the progit2 build script want us using the latest development version at the time you run bundle install (see below). All other tools needed to build the book are included in the Booksquisher Docker image.

What You Don’t Need

The wonderful thing about Docker is that you don’t need to have Asciidoctor, Ruby, or other book-building software installed on your local computer (or the associated interlocking maze of dependencies and version requirements). The Booksquisher Docker image contains all the necessary tools to take the book source code as input and generate high-quality formatted books in EPUB3, Kindle Format 8 (AZW3/MOBI), PDF, and HTML5 format as output. The Docker image has all the tools to do this for the Booksquisher Example Book Templates, the Pro Git 2 book, the User’s Guide you are reading now, or for creating your own books.