README

   1 Conv - convert files according to rules
   2
   3 Conv is a utility similar to "make" -- it uses a set of rules (by
   4 default a file called Convfile) to transform files via program
   5 execution.  Conv is considerably simpler than make, though.  Conv
   6 doesn't:
   7
   8 * Recursively resolve inferences - Conv specifies a single command to
   9   convert from one file format to another.
  10 * Work on arbitrary patterns - Conv's rules only specify how to convert
  11   from one file extension to another.
  12 * Support a large set of variable manipulation functions - You get
  13   variable substitution, and that's it.
  14
  15 Which is not to say that conv is useless. Far from it. Conv does:
  16
  17 * Support spaces in filenames - Make doesn't do this (well), and this
  18   limitation was the primary impetus for creating conv.
  19 * Provide a simple way to batch convert files - A single conv invocation
  20   can convert all files in a directory to a specified format.
  21 * Support multiprocessing - Conv uses the familiar -j switch to execute
  22   multiple conversions simultaneously.
  23 * Tell you what it's thinking - The -v switch will shed some light on
  24   how conv is finding files to convert.
  25 * Do nothing (if you want) - The -n switch will show you what would be
  26   executed, but stop short of actually executing anything.
  27 * Use alternate rules - The -f <file> switch will use a rule file other
  28   than Convfile.
  29 * Output to a different directory - The -o <dir> switch will make conv
  30   put output files in another directory, even if the file you're
  31   specifying is not in the current directory.
  32
  33 == Invocation ==
  34
  35 conv [-f <file>] [-i <ext>] [-o <dir>|<file>] [-s] [-j <procs>] [-n] [-v]
  36      <file1> [<file2> ... <filen>]
  37
  38         -f <file>       Use the specified rule file instead of Convfile.
  39         -i <ext>        Files specified are input files instead of output
  40                         files, and will be converted to files with the given
  41                         extension.
  42         -o <dir>|<file> Place output files in the specified directory or file.
  43                         Note that -o <file> implies -i <ext> using <file>'s
  44                         extension.  Multiple input files can be specified with
  45                         a single output file, but this may not make sense.  On
  46                         the other hand, if your output file is a device or
  47                         fifo, it could make sense.
  48         -s              Read filenames from stdin instead of from the
  49                         command-line.
  50         -j <procs>      Spawn <procs> conversions at once, for
  51                         multiprocessor machines.
  52         -n              Don't actually do anything. Useful with -v to find out
  53                         what conv is thinking.
  54         -v              Be more verbose.
  55
  56 It is important to realize that, just like make, the files you are specifying
  57 are the _output_ files, not the input files (unless, of course, you've
  58 specified the -i switch).  The input files are found automatically from the
  59 first matching rule where a file exists.  This means that if you have foo.ogg,
  60 and you want to produce a mp3, you should do this:
  61
  62 $ conv foo.mp3
  63
  64 As a special case, if one of the files specified is exactly '*.<ext>',
  65 conv will try to convert every file in the current directory into a
  66 <ext> file, as though you had typed out "<file>.<ext>" manually for each
  67 file.  Do note that if you actually have any files with extension <ext>
  68 in the current directory, it is likely that your shell will expand the
  69 glob before conv gets the command line.  This might not be what you
  70 expected, so if in doubt, escape the *.
  71
  72 == Examples ==
  73
  74 1. Convert a directory full of flac files to mp3s using lame.
  75
  76    --Convfile--
  77    flac => mp3 : lame --quiet -h $< $@
  78    --cut--
  79
  80    $ conv *.mp3
  81
  82 2. Convert a movie in AVI format to something an iPod can chew on (but
  83    you would probably want to use a separate script for the actual
  84    conversion).
  85
  86    --Convfile--
  87    avi => mp4 : ffmpeg -i $< -s 320x240 -vcodec xvid -b 900k -acodec mp3 -ab 96 $@
  88    --cut--
  89
  90    $ conv "drift bible.mp4"
  91
  92 == Convfile format ==
  93
  94 A Convfile has a simple format, which some might say looks like a
  95 makefile mated with a perl script.  This was intentional.  :)  Every
  96 line in a Convfile is either blank, or one of two types:
  97
  98 * A rule, which looks like:
  99
 100   foo => bar : program $< $@
 101
 102   Which says "Convert files with extension 'foo' to a file with
 103   extension 'bar' using program 'program'.  $< and $@ mean "input" and
 104   "output," respectively, and are substituted with the input and output
 105   filenames, just like make does.  Note that conv considers an extension
 106   to be made up of letters and numbers ONLY.  If this isn't sufficient,
 107   go hack the regex yourself.  :P
 108
 109 * A variable declaration, which looks like:
 110
 111   foo = bar
 112
 113   Which says "Set the variable foo to the value 'bar'".  Later, the
 114   variable can be used by saying $foo.  Unlike make, we don't require
 115   you to do something silly like put parentheses around the variable
 116   name.  Variables are case-sensitive, and can be made up of any
 117   sequence of letters, numbers, and underscores, except that it can't
 118   start with a number (Why? To be consistent with other things. Again,
 119   the regex is there).  Variables are not substituted into commands
 120   until execution, so you could put the variables at the end of the
 121   file, though I have no idea why you would do that.
 122
 123 You can put comments anywhere in the file as well, they're simply a #
 124 followed by whatever you want up until the end of the line.