[cairo] redesigning the arguments for svg2png

[Jason Dorje Short]

Current arguments for svg2png:

  -w $WIDTH
  -h $HEIGHT
  -s $SCALE
  -x, --flipx
  -y, --flipy
  input.svg and output.png are taken directly as parameters

This is all explained in `man svg2png`.  The problem is it's incomplete.

----------

For instance if you give -w and -h svg2png makes an image with the given
$WIDTH and $HEIGHT and puts the SVG file inside it with preserved aspect
ratio.  Thus there is no distortion and there is padding.

One thing I need to do is to change the aspect ratio.  I want to give a
width and height and have the SVG "stretch" to take up this whole area.
 Thus the xscale and yscale are different.  Thus there is distortion and
there's no padding.  This is what rsvg, sodipodi, and inkscape
command-line renderers do.

A third thing one would want to do is preserve the aspect ratio but
without any padding.  Thus the $WIDTH and $HEIGHT provide the max
dimensions, just like svg2png does now, but without any padding.  Thus
there is no distortion and there is no padding.  IIRC this is what the
librsvg rsvg_pixbuf_from_file_at_max_size function does (which I've
found very useful in the past).

Yet another thing you might want to do is specify the xscale and yscale
independently.  I can't recall ever needing to do this, but rsvg allows it.

Finally, one might wish to specify things in DPI.  If the SVG image is
given in real-world dimensions (e.g., inches) giving a DPI to render at
will allow you to make the PNG image show up at the right size when
rendered at that DPI (to a monitor or a printer).  Aspect ratio is
preserved; this is just a (possibly) convenient way of setting the
--scale.  Inkscape provides a -d $DPI parameter allowing this.  Note
that this will not work with all SVG files.

----------

Of course svg2png should be able to do all of the above tasks.  It would
also be nice to keep command-line compatibility with rsvg, inkscape,
sodipodi.  The trick is to do all this without having confusingly many
options or giving unexpected default behavior.

Thus I suggest:

  --width=$WIDTH (-w)
  --height=$HEIGHT (-h)
  --xscale=$X_SCALE (-x)
  --yscale=$Y_SCALE (-y)
  --flipx (-X maybe?)
  --flipy (-Y maybe?)
  --scale=$SCALE (-s)
  --dpi=$DPI (-d)
  --pad [1]
  --stretch

You may pad or stretch or neither but not both.  The default should be
to do neither (same as rsvg, inkscape, and sodipodi), this changes the
current behavior which is to pad.  (--pad and --stretch were suggested
by Carl.)

Supporting -d will require new functions to libsvg and libsvg-cairo to
set the DPI.

-x and -y are changed from flipx and flipy to xscale and yscale.  This
matches the rsvg args (they call it --x-zoom, --y-zoom).

In case of conflicting options (--width and --xscale both given) the one
higher up in the list is given priority (this is obviously arbitrary and
can be tweaked a bit).  Care should be taken to give a sensible output
no matter what combination of args are given (rsvg is pretty bad at this).

----------

For full compatibility with inkscape and rsvg it would be necessary to
add more "long argument" aliases.  This would be convenient but would
also add clutter to the interface.

Inkscape also has some additional parameters that might be useful,
either for new features or compatibility.  See -a, -f, -e, -i, -j, -t,
-b, -y from `man inkscape`.  I don't understand all of these but some of
them are probably desirable.

In a related note xsvg should probably support a similar set of options.
 Seems there could be a lot of overlap here.

-jason