rewrite documentation

doc/config

@@ -1,7 +1,86 @@
-/etc/atom
-`-- source
-`-- targets/
-|   `-- target1
-|   `-- target2
-|   `-- …
-`-- atom.conf
+On first launch, AtOM will create an example configuration file for you. This is
+only an example, suitable to *my* needs (I'm lazy).
+Default config file is ~/.atom/atom.cfg.
+
+The file is divided in sections, beginning with [<sectionname>]. The section
+ends where the next one begins. Inside each sections, properties are defined
+with <key><space><value>, where <space can be either spaces, tabulations, or a
+mix of both. <key> is always a single word. <value> shall never be quoted,
+whether it contains spaces or not.
+
+For example the following defines 'path' as '/usr/share/the big music library':
+path        /usr/share/the big music library
+If '/usr/share/the big music library' is quoted, quotes would be included in the
+value.
+
+Sections:
+[general]
+  This section contains parameters of the program itself.
+
+  * max-load <load>: Integer. Defines how parallel processing will behave. AtOM
+      will try to keep the 1 minute load average between <load> and <load>+1 by
+      adjusting concurrency.
+      Initial concurrency will be set to half of that value.
+  * load-interval <seconds>: Integer. How often should we check the load average
+      and adjust concurrency. Set this too low, and concurrency may be increased
+      too quickly. Set this too high, and AtOM will not adapt quickly enough to
+      load increase. In both cases, your hard drive will suffer. In my
+      experience, 30 seconds is a good value.
+  * temporary-directory <directory>: String. Name speaks for itself:this is where FIFOs (for
+      communicating with sqlite) and temporary WAVE files will be created.
+      Note that debug logs (if enabled) will go there too.
+      Default: ~/.atom/tmp
+  * database <file>: String. Where the SQLite databse should be stored.
+      Default: ~/.atom/atom.db
+  * debug <level>: Integer. Currently defined values:
+      * 3: log SQL queries.
+
+[source]
+  This section defines where are the files you want transcoded.
+
+  * path <directory>: String. The root of your collection.
+      Default: /var/lib/mpd/music
+  * id3charset <charset>: String. FLAC and Ogg Vorbis use UTF-8, but ID3 may use
+      some other charset. Wrong settings can result in strangely tagged files.
+
+[<some arbitrary string>]
+  Each section not named 'general' or 'source' will define a new destination.
+
+  Common parameters:
+   Mandatory parameters:
+    * path: Where files will be written
+    * format: ogg or mp3 (other formats may appear in the future - feel free to
+      implement your preferred format. A good candidate is FIXME).
+
+   Optional parameters:
+    * rename <string>: Destination files will be named according to <string>,
+      after expansion of special strings:
+        %{album},
+        %{albumartist},
+        %{artist},
+        %{genre},
+        %{title},
+        %{track},
+        %{year}.
+      Untagged files or files in unrecognized formats will not be changed.
+    * skip_mime-type <mime-type>: Files with mime-type <mime-type> will not
+      be included in that destination. For more than one mime-type, use multiple
+      times, as needed. The '*' character is a wildcard.
+    * copy_mime-type <mime-type>: Same as skip_mime-type, except that files
+      matching will be copied as-is to tha destination. E.g. image/* will copy
+      covers and other images to the destination. In fact, AtOM will try to use
+      hard links instead of copies.
+    * channels <number>: Files with more than <number> channels will be
+      downmixed. Useful if you create files for telephony music-on-hold.
+    * frequency <hertz>: Files will be resampled as needed to <hertz>Hz
+      sampling-rate. Shoutcast/Icecast streams require a constant sampling-rate.
+      Telephony systems often require a sample rate of 8000Hz.
+
+  Ogg parameters:
+    * quality <quality>: The quality parameter of oggenc. See man oggenc for
+      more info. This is the only mode supported and planned. Still, if you want
+      to be able to use bitrate settings, feel free to fork and file a pull
+      request.
+  MP3 parameters:
+    * bitrate <bitrate>: Set ABR to <bitrate>. Again, if you want CBR or any
+      other mode supported by lame, please fork and file a pull request.