README

   1 = minicomic
   2
   3 +minicomic+ is a library providing a set of rake rules for building
   4 print and web-ready files for minicomics from a set of SVG files.
   5
   6 Originally designed for generating black-and-white folio minicomics of the sort
   7 most suited for inexpensive photocopying, the most recent versions produce
   8 color output by default.  If you are generating classic black-and-white
   9 minicomics, the options:
  10
  11  :color => :monochrome, :rasterize => false
  12
  13 are recommended for getting optimum quality and file sizes.
  14
  15 == getting minicomic
  16
  17 +minicomic+ is available from Rubyforge:
  18
  19 http://www.rubyforge.org/projects/minicomic
  20
  21 Or via RubyGems:
  22
  23  sudo gem install minicomic
  24
  25 Development versions are available via git from repo.or.cz:
  26
  27  git://repo.or.cz/minicomic.git
  28  http://repo.or.cz/r/minicomic.git
  29
  30 == requirements
  31
  32 In addition to the obvious requirements for Ruby and Rake, +minicomic+
  33 requires the following software to be installed and available on your
  34 shell's path:
  35
  36 * Inkscape
  37 * psutils
  38 * Ghostscript
  39 * ImageMagick
  40 * pngcrush
  41
  42 If you're on Ubuntu, these correspond to the +inkscape+, +psutils+,
  43 <tt>gs-gpl</tt>, +imagemagick+ and +pngcrush+ packages, respectively.
  44
  45 == usage
  46
  47 The simplest way to use +minicomic+ is to create a +Rakefile+ as follows:
  48
  49   require 'minicomic'
  50
  51   minicomic '.'
  52
  53 +minicomic+ will either look for pages in a <tt>pages/</tt> folder in the
  54 given directory (in this particular case, '.' meaning the directory where the
  55 +Rakefile+ lives), or for a <tt>pages.yaml</tt> file in the given directory.
  56 Options can be included after the directory name, for instance:
  57
  58   minicomic '.', :color => false
  59
  60 (specific options will be discussed later)
  61
  62 There are two ways to define the files and options that will be used to
  63 generate the comic: within the pages directory or by a definition
  64 file called pages.yaml.  <tt>pages.yaml</tt> takes precedence over
  65 the <tt>pages/</tt> directory.
  66
  67 === within the pages directory
  68
  69 In the pages directory, +minicomic+ looks for SVG files named according to the
  70 following conventions:
  71
  72 <tt>page-NN.svg</tt>:: page +NN+
  73 <tt>front-cover.svg</tt>:: the front cover of the comic (optional)
  74 <tt>back-cover.svg</tt>:: the back cover of the comic (optional)
  75 <tt>inside-front.svg</tt>:: the inside front cover of the comic (optional)
  76 <tt>inside-back.svg</tt>:: the inside back cover of the comic (optional)
  77
  78 Page numbers start at 1 (page 1 is a right-handed page, and the first
  79 interior page excluding the inside cover,  unless <tt>:use_inside</tt> is true).
  80 The exact size of page documents is not important; they will be scaled to fit
  81 the selected output format (preserving aspect ratio).
  82
  83 It is also possible to have two-page spreads in single files:
  84
  85 <tt>pages-NN-MM.svg</tt>:: the spread spanning pages <tt>NN</tt>-<tt>MM</tt>
  86 <tt>cover.svg</tt>:: the cover (back and front together in one file; optional)
  87
  88 A two-page spread will be cut in half and each half placed on the appropriate
  89 page in the print output.
  90
  91 === by definition file
  92
  93 pages.yaml is a YAML file in the following format:
  94
  95 <tt>- file: "page-one.svg"</tt>:: a single comic page
  96 <tt>- blank: true</tt>:: a blank page
  97 <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)
  98 <tt>- { file: "two-page-spread.svg", spread: true }</tt>:: a two-page spread
  99
 100 Pages within the YAML file are numbered sequentially starting at page 1.  Pages
 101 that are assigned to special names do not count in the page number ordering.
 102
 103 == print output
 104
 105 When generating output for print, +minicomic+ will round the number of
 106 interior pages up to the next multiple of four, padding with blank pages
 107 as needed.  The page graphics will be scaled down slightly from their full
 108 size, and smaller graphics will be centered.
 109
 110 === print-related options
 111
 112 There are several options which control how minicomic's print output is
 113 generated:
 114
 115 <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>)
 116 <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+)
 117 <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)
 118 <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+)
 119 <tt>:half_size</tt>:: if +true+, will double up the image on the page vertically to produce mini-minicomics (default: +false+)
 120
 121 If the pages are rasterized, then the following options also apply to print:
 122
 123 <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>)
 124 <tt>:dpi</tt>:: the target DPI for the rasterized page images (taking into account any scaling to accomodate the margins) (default: +200+)
 125 <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+)
 126
 127 === proof output
 128
 129 To generate a "proof" PDF that you can examine to see what spreads will
 130 look like in the assembled comic (i.e. "reader spreads"), use:
 131
 132  rake proof
 133
 134 The PDF will be created as <tt>print/proof.pdf</tt>.  Since I rarely use the
 135 inside covers for anything, +minicomic+ currently places the front and back
 136 covers opposite the first and last interior pages respectively.
 137
 138 === single-sided printing
 139
 140 To generate a set of PDFs suitable for single-sided printing and assembly, use:
 141
 142   rake single
 143
 144 This will generate a set of two PDFs:
 145
 146 <tt>print/front.pdf</tt>:: front side of all pages
 147 <tt>print/back.pdf</tt>:: back side of all pages
 148
 149 When using the single-sided PDFs, _you will need to experiment_ to find the
 150 correct order to use them in, and the correct way to flip the paper.  For my
 151 printer, I print <tt>back.pdf</tt> first, then flip the stack the long way
 152 before printing <tt>front.pdf</tt> on it.  Other printers will differ depending
 153 on how the paper is loaded in the tray, and how it is stacked on output.
 154
 155 === duplex printing
 156
 157 To generate a set of PDFs suitable for duplex printing and assembly, use:
 158
 159   rake duplex
 160
 161 This will generate a single PDF, <tt>print/duplex.pdf</tt>.
 162
 163 When printing this PDF, if you're lucky, your printer it will deposit its
 164 output pages face-down and they will be ready for assembly (this is the norm).
 165 Otherwise if it deposits its pages face-up, you will have to reverse their order
 166 before you can assemble the comic.
 167
 168 == web output
 169
 170 You can generate files for web upload via:
 171
 172  rake web
 173
 174 === web-related options
 175
 176 The following options apply to web output:
 177
 178 <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>)
 179 <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)
 180 <tt>:web_jpeg_quality</tt>:: the JPEG quality of the outputted JPEG files from 0-100 (default: 75)
 181 <tt>:generate_thumbnails</tt>:: generate thumbnail images (default: +true+)
 182 <tt>:thumbnail_height</tt>:: the height, in pixels, of thumbnail images (default: 96)
 183 <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>)
 184
 185 === output files
 186
 187 When generating output for the web, +minicomic+ will generate a set of either PNGs
 188 or JPEGs and a corresponding set of JPEG thumbnails if <tt>:generate_thumbnails</tt> is +true+:
 189
 190 <tt>web/page-NN.png</tt>:: page +NN+ as a PNG
 191 <tt>web/page-NN.jpeg</tt>:: page +NN+ as a JPEG
 192 <tt>web/thumbnail-NN.jpeg</tt>:: thumbnail of page +NN+
 193
 194 For spreads, the filenames are similar, except instead of a single page number
 195 +NN+, a page range will be indicated as <tt>NN-MM</tt>.
 196
 197 == cleanup
 198
 199 You can easily get rid of the temporary and output files with:
 200
 201  rake clean
 202
 203 This is often a good idea if you've changed any of minicomic's options, since
 204 files generated with the previous options may still be lingering.
 205