= minicomic

+minicomic+ is a library providing a set of rake rules for building
print and web-ready files for minicomics from a set of SVG files.

Originally designed for generating black-and-white folio minicomics of the sort
most suited for inexpensive photocopying, the most recent versions produce
color output by default.  If you are generating classic black-and-white
minicomics, the options:

 :color => :monochrome, :rasterize => false

are recommended for getting optimum quality and file sizes.

== getting minicomic

+minicomic+ is available from Rubyforge:

http://www.rubyforge.org/projects/minicomic

Or via RubyGems:

 sudo gem install minicomic

Development versions are available via git from repo.or.cz:

 git://repo.or.cz/minicomic.git
 http://repo.or.cz/r/minicomic.git

== requirements

In addition to the obvious requirements for Ruby and Rake, +minicomic+
requires the following software to be installed and available on your
shell's path:

* Inkscape
* psutils
* Ghostscript
* ImageMagick
* pngcrush

If you're on Ubuntu, these correspond to the +inkscape+, +psutils+,
<tt>gs-gpl</tt>, +imagemagick+ and +pngcrush+ packages, respectively.

== usage

The simplest way to use +minicomic+ is to create a +Rakefile+ as follows:

  require 'minicomic'

  minicomic '.'

+minicomic+ will either look for pages in a <tt>pages/</tt> folder in the
given directory (in this particular case, '.' meaning the directory where the
+Rakefile+ lives), or for a <tt>pages.yaml</tt> file in the given directory.
Options can be included after the directory name, for instance:

  minicomic '.', :color => false

(specific options will be discussed later)

There are two ways to define the files and options that will be used to
generate the comic: within the pages directory or by a definition
file called pages.yaml.  <tt>pages.yaml</tt> takes precedence over
the <tt>pages/</tt> directory.

=== within the pages directory

In the pages directory, +minicomic+ looks for SVG files named according to the
following conventions:

<tt>page-NN.svg</tt>:: page +NN+
<tt>front-cover.svg</tt>:: the front cover of the comic (optional)
<tt>back-cover.svg</tt>:: the back cover of the comic (optional)
<tt>inside-front.svg</tt>:: the inside front cover of the comic (optional)
<tt>inside-back.svg</tt>:: the inside back cover of the comic (optional)

Page numbers start at 1 (page 1 is a right-handed page, and the first
interior page excluding the inside cover,  unless <tt>:use_inside</tt> is true).
The exact size of page documents is not important; they will be scaled to fit
the selected output format (preserving aspect ratio).

It is also possible to have two-page spreads in single files:

<tt>pages-NN-MM.svg</tt>:: the spread spanning pages <tt>NN</tt>-<tt>MM</tt>
<tt>cover.svg</tt>:: the cover (back and front together in one file; optional)

A two-page spread will be cut in half and each half placed on the appropriate
page in the print output.

=== by definition file

pages.yaml is a YAML file in the following format:

<tt>- file: "page-one.svg"</tt>:: a single comic page
<tt>- blank: true</tt>:: a blank page
<tt>- { file: "full-cover.svg", page_name: "cover" }</tt>:: a comic page that is assigned to a particular special page 
in the comic (front-cover, back-cover, cover, inside-front, or inside-back)
<tt>- { file: "two-page-spread.svg", spread: true }</tt>:: a two-page spread

Pages within the YAML file are numbered sequentially starting at page 1.  Pages
that are assigned to special names do not count in the page number ordering.

== print output

When generating output for print, +minicomic+ will round the number of
interior pages up to the next multiple of four, padding with blank pages
as needed.  The page graphics will be scaled down slightly from their full
size, and smaller graphics will be centered.

=== print-related options

There are several options which control how minicomic's print output is
generated:

<tt>:paper</tt>:: the size of the paper the comic will be printed on; options are <tt>:letter</tt>, <tt>:legal</tt>, 
<tt>:tabloid</tt>, <tt>:a4</tt>, <tt>:a5</tt>, <tt>:b5</ii>, or a two-element array with dimensions in postscript points 
(default: <tt>:letter</tt>)
<tt>:rasterize</tt>:: whether print output should be rasterized rather than being exported as PostScript -- PostScript 
will usually result in smaller files, but cannot support many Inkscape features like blur or transparency (default: 
+true+)
<tt>:margin</tt>:: a nominal horizontal margin in PostScript points; the page images will be scaled down slightly to 
accomodate this margin (default: +13.5+, which is 3/16 of an inch)
<tt>:use_inside</tt>:: if +true+, will set page 1 to be a left-handed page, on the opposite side of the cover (default: 
+false+)
<tt>:half_size</tt>:: if +true+, will double up the image on the page vertically to produce mini-minicomics (default: 
+false+)

If the pages are rasterized, then the following options also apply to print:

<tt>:color</tt>:: <tt>true</tt>, <tt>false</tt>, or <tt>:monochrome</tt> -- whether the rasterized images should be 
full-color, greyscale, or monochrome (24-bit color, 8-bit greyscale, or 1-bit bitmap) (default: <tt>false</tt>)
<tt>:dpi</tt>:: the target DPI for the rasterized page images (taking into account any scaling to accomodate the 
margins) (default: +200+)
<tt>:force_dpi</tt>:: if non-SVG images are loaded whose DPI is higher than the target <tt>:dpi</tt>, scale the image so 
that it uses the specified <tt>:dpi</tt> (default: +false+)

=== proof output

To generate a "proof" PDF that you can examine to see what spreads will
look like in the assembled comic (i.e. "reader spreads"), use:

 rake proof

The PDF will be created as <tt>print/proof.pdf</tt>.  Since I rarely use the
inside covers for anything, +minicomic+ currently places the front and back
covers opposite the first and last interior pages respectively.

=== single-sided printing

To generate a set of PDFs suitable for single-sided printing and assembly, use:

  rake single

This will generate a set of two PDFs:

<tt>print/front.pdf</tt>:: front side of all pages
<tt>print/back.pdf</tt>:: back side of all pages

When using the single-sided PDFs, _you will need to experiment_ to find the
correct order to use them in, and the correct way to flip the paper.  For my
printer, I print <tt>back.pdf</tt> first, then flip the stack the long way
before printing <tt>front.pdf</tt> on it.  Other printers will differ depending
on how the paper is loaded in the tray, and how it is stacked on output.

=== duplex printing

To generate a set of PDFs suitable for duplex printing and assembly, use:

  rake duplex

This will generate a single PDF, <tt>print/duplex.pdf</tt>.

When printing this PDF, if you're lucky, your printer it will deposit its
output pages face-down and they will be ready for assembly (this is the norm).
Otherwise if it deposits its pages face-up, you will have to reverse their order
before you can assemble the comic.

== web output

You can generate files for web upload via:

 rake web

=== web-related options

The following options apply to web output:

<tt>:web_format</tt>:: the format for web output images; options are <tt>:png</tt> or <tt>:jpg</tt>/<tt>:jpeg</tt> 
(default: <tt>:png</tt>)
<tt>:web_height</tt>:: the height, in pixels, of images for web output (width will be determined according to the page's 
aspect ratio) (default: 680)
<tt>:web_jpeg_quality</tt>:: the JPEG quality of the outputted JPEG files from 0-100 (default: 75)
<tt>:generate_thumbnails</tt>:: generate thumbnail images (default: +true+)
<tt>:thumbnail_height</tt>:: the height, in pixels, of thumbnail images (default: 96)
<tt>:color</tt>:: whether the generated images should be 24-bit color (+true+), 8-bit greyscale (+false+), or 4-bit 
greyscale (<tt>:monochrome</tt>) (default: <tt>true</tt>)

=== output files

When generating output for the web, +minicomic+ will generate a set of either PNGs
or JPEGs and a corresponding set of JPEG thumbnails if <tt>:generate_thumbnails</tt> is +true+:

<tt>web/page-NN.png</tt>:: page +NN+ as a PNG
<tt>web/page-NN.jpeg</tt>:: page +NN+ as a JPEG
<tt>web/thumbnail-NN.jpeg</tt>:: thumbnail of page +NN+

For spreads, the filenames are similar, except instead of a single page number
+NN+, a page range will be indicated as <tt>NN-MM</tt>.

== cleanup

You can easily get rid of the temporary and output files with:

 rake clean

This is often a good idea if you've changed any of minicomic's options, since
files generated with the previous options may still be lingering.