= 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.