Quarto Yet another ebook generation toolchain, biased towards writing books about programming. About the name: "Quarto" is a bookbinding te…
Quarto Yet another ebook generation toolchain, biased towards writing books about programming. About the name: "Quarto" is a bookbinding te…
Yet another ebook generation toolchain, biased towards writing books about programming.
About the name: "Quarto" is a bookbinding term, and this is my fourth attempt at a reusable ebook toolchain.
Development on Quarto will necessarily occur in fits and starts, because I'll only be working on it actively while I'm writing a book.
It is also very, very unsupported. Right now it exists to solve my problems... barely. If it solves your problems too that's fantastic, but I don't have time to help you get it working. available!
Quarto depends on several external programs which you will need to install before using it. Some of these are only required if you use the corresponding plugin.
Note: Quarto is available as a Ruby gem, which you can install in the
usual way (gem install quarto). But while the gem provides
stability, it is laughably out of date. Indeed, installing the gem
(instead of pointing to a GitHub repository) almost guarantees that
these instructions will not work.
Create a new directory, in which your book project will reside:
mkdir mybook
Inside of the directory, create a Rakefile, containing the
following:
require 'quarto/tasks' This Rakefile is what you will use to run Quarto's Rake tasks,
which are what you will use to create and publish your book.
Now create a Gemfile. This will be used by
Bundler to install the required Ruby gems,
including Quarto. The Gemfile should look, at a minimum, like
this:
gem 'rake'
gem 'quarto', github: 'avdi/quarto'Note that this is true if you want to be using the original, Avdi Grimm-authored version of Quarto. If, by contrast, you want fork Quarto into your own GitHub repository, then you will want to point to that.
Now run bundle install, which will create a Gemfile.lock.
Run rake -T to see the available tasks.
The task you care about is probably rake deliverables. (This is also the default.)
Quarto is a set of Rake tasks backed up by a Ruby library, which in turn relies heavily on Nokogiri and a number of external tools.
Quarto doesn't (yet) introduce any revolutionary ideas to e-publishing. Instead, it ties familiar tools together in a way that lets you write the way you want to.
There are a lot of tools that try to tie together an end-to-end publishing pipeline. But when you want to interpose your own processing in between steps, you're out of luck. The fact that Quarto is structured as a set of Rake tasks means that you can add your own dependencies, your own steps, or tack extra processing onto any of the existing steps just by adding to your project's Rakefile.
There is a well-defined set of steps with documented inputs and output artifacts (see below). These artifacts of the build process are left behind in a build directory in your project root, so it's easy to understand what Quarto is doing at each step of the way. There's nothing hidden in anonymous temporary files.
Quarto tries to pick the best tools for each step in the book-building chain. So for instance, while some Markdown parsers support limited syntax highlighting of source code, Quarto instead uses Pygments to highlight code listings as a separate (and highly optimized) step. This ensures that high-quality highlighting is available for the widest possible variety of source code languages.
When there is an option to either perform an operation in pure Ruby and shell out to a command-line tool without too much added pain, Quarto prefers to shell out to the tool. This may seem counterintuitive, since it means more dependencies. The advantage is that since Rake echoes shell commands to the console, you can see exactly what Quarto is doing. You can even copy and paste the commands to try them yourself.
In the future, I hope to make it so that even tasks that are implemented in pure Ruby can be easily invoked independently from the command line. The goal is to have the output of a Quarto run be a series of commands that you could run manually and get the same results.
A central philosophy of Quarto is to do as much work as possible with XHTML5 files. All input formats (e.g. Markdown) are first converted to XHTML5 before any other work is done. Then various transformations occur. Finally, at the end of the line, an XHTML5 "master" file is converted to various deliverable formats such as PDF. The reason for this philosophy is simple: Nokogiri makes it really easy to perform arbitrary semantic transformations on XHTML documents, without a lot of tedious mucking about with text munging. The more of the work that is done on DOM object trees, the easier it is to do.
XHTML5 is also sufficiently rich and expressive that most formats can be converted to it without losing information. And XHTML5 is at the heart of both EPUB3 and Kindle Format 8, the leading ebook publishing formats.
Quarto is a set of Rake tasks, so execution normally starts with a desired end product and works backwards through the dependency chain to figure out what needs to be done to produce that product. However, it's probably easier to understand everything Quarto does by viewing it as an assembly line starting with source files and ending with deliverables. Here are the steps along the way.
Note that all files generated by Quarto are placed in a build subdirectory of your project's root. It will be created if needed.
build/export. Export files are HTML, produced using whatever tool is appropriate for the input format. E.g. pandoc is used to export Markdown source files to HTML equivalents.build/signatures). During this normalization process any idiosyncrasies in the HTML produced by the export tool are dealt with.build/listings). Listing files are named based on the SHA1 of the listing and its language, e.g. build/listings/3361c5f02e08bd44bde2d42633a2c9be201f7ec4.rb. Using the SHA1 in naming is an optimization which ensures that only changed code listings ever need to be re-highlighted (see the next step). During this step a skeleton file is also created. This XHTML file mirrors the codex file, except that all of the source code listings have been replaced with references to highlight files (see next step).build/highlights directory. They named based on the SHA1 of the corresponding code listing.Quarto can be configured by requiring quarto instead of quarto/tasks, and calling Quarto.configure. Here is the configuration for my book "Confident Ruby":
…By default Quarto seeks out source files with extensions it knows about. Alternatively, you can explicitly define the list of source files to use, and the order in which to use them.
Quarto.configure do |config|
config.source_files generate_text
end
# Add support methods as you need
def generate_text
#... your implementation
end
end
endYou can access your plugin through the Quarto config object:
Quarto.configure do |config|
config.use :text_output
endQuarto will take the argument from the config.use call to determine the name of your plugin class. The argument :text_output will be translated to "TextOutput"
When hooking into the config object, Quarto expects your plugin to be stored (using this example) in "quarto/text_output". Your plugin should be created under the Quarto namespace. Quarto will attempt to find it using Quarto.const_get meaning it will look inside its own namespace.
git checkout -b my-new-feature)git commit -am 'Add some feature')git push origin my-new-feature)No open issues yet, or sync has not completed.