Some documentation updates

INSTALL

@@ -1,14 +1,8 @@
 Installation instructions for forked-daapd
 ------------------------------------------
 
-There are two ways to install forked-daapd: from a tarball or from the git
+This document contains instructions for installing forked-daapd from the git
-tree. The tarball contains a working build system and pre-generated ANTLR3
+tree.
-parsers; the git tree doesn't and requires more tools to generate the build
-system and the ANTLR3 parsers.
-
-In both cases the installation procedure is the traditional ./configure;
-make; make install. Please read this file carefully before proceeding.
-
 
 System-specific requirements:
  - Linux:
@@ -18,10 +12,13 @@ System-specific requirements:
    + OSS4 sound support
    + libiconv
 
-Tools:
+Tools required:
- - pkg-config
+ - autotools-dev
- - gperf 3.x
+ - autoconf
-        from <http://www.gnu.org/software/gperf/>
+ - libtool
+ - gettext
+ - gawk
+ - gperf
 
 Libraries:
  - libantlr3c (ANTLR3 C runtime, version 3.2 for tarball builds)
@@ -34,7 +31,7 @@ Libraries:
         from <http://libav.org/releases/>
  - libconfuse
         from <http://www.nongnu.org/confuse/>
- - libevent 1.4+
+ - libevent 1.4 (** NOT libevent 2 **)
         from <http://www.monkey.org/~provos/libevent/>
  - libavl
         /!\ Read below
@@ -75,21 +72,23 @@ libav (ffmpeg) is a central piece of forked-daapd and most other FLOSS
 multimedia applications. The version of libav you use will potentially have a
 great influence on your experience with forked-daapd.
 
-The following versions of libav (ffmpeg) are supported and known to work:
+forked-daapd supports older versions of libav and ffmpeg, but for libav 0.8.x
- - ffmpeg 0.5.x: has issues with metadata (tags) extraction, notably with
+is known to be working. If you use a new version of libav or ffmpeg you may
-   MP3 files and ID3 tags in general;
+encounter issues with MP3 files with embedded artwork, as forked-daapd may
- - libav 0.6.x: known to work better with regard to metadata extraction;
+classify them as video files.
- - libav 0.7.x: better yet
-
-Note that forked-daapd uses libav since the ffmpeg/libav fork during the
-0.6.x series.
 
 
 Building from the git tree
 --------------------------
 
-Gitweb: <http://git.debian.org/?p=users/jblache/forked-daapd.git>
+The source for this version of forked-daapd can be found here:
-Git tree: <git://git.debian.org/users/jblache/forked-daapd.git>
+
+  <https://github.com/ejurgensen/forked-daapd.git>
+
+The original (now unmaintained) source can be found here:
+
+  <http://git.debian.org/?p=users/jblache/forked-daapd.git>
+  <http://alioth.debian.org/~jblache/forked-daapd/>
 
 Required tools:
  - ANTLR v3 is required to build forked-daapd, along with its C runtime
@@ -122,14 +121,7 @@ by ANTLR3.
 The parsers will be generated during the build, no manual intervention is
 needed.
 
-
+To display the configure options run ./configure --help
-Building from the tarball
--------------------------
-
-Download URL: <http://alioth.debian.org/~jblache/forked-daapd/>
-
-When building forked-daapd from a release tarball, the usual ./configure;
-make; make install procedure applies.
 
 FLAC and Musepack support are optional. If not enabled, metadata extraction
 will fail on these files.
@@ -138,14 +130,15 @@ Support for iTunes Music Library XML format is optional. Use --enable-itunes
 to enable this feature.
 
 Recommended build settings:
- ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var --enable-flac --enable-musepack
+ ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var --enable-flac
+
+After configure run the usual make, and if that went well, sudo make install
 
 After installation, edit the configuration file, /etc/forked-daapd.conf and
 adjust the values at your convenience.
 
 forked-daapd will drop privileges to any user you'll specify in the
-configuration file if it's started as root. It's recommended to create a
+configuration file if it's started as root.
-dedicated user without login privileges.
 
 This user must have read permission on your library (you can create a group for
 this and make the user a member of the group, for instance) and read/write
@@ -169,13 +162,15 @@ The LSB header below sums it up:
 
 ### BEGIN INIT INFO
 # Provides:          forked-daapd
-# Required-Start:    $local_fs $remote_fs $network $time avahi
+# Required-Start:    $local_fs $remote_fs $network $time
 # Required-Stop:     $local_fs $remote_fs $network $time
+# Should-Start:      avahi
 # Default-Start:     2 3 4 5
 # Default-Stop:      0 1 6
 # Short-Description: media server with support for RSP, DAAP, DACP and AirTunes
 # Description:       forked-daapd is an iTunes-compatible media server for
-#                    sharing your music library over the local network with RSP
+#                    sharing your media library over the local network with RSP
-#                    clients like the SoundBridge from Roku and DAAP clients like
+#                    clients like the SoundBridge from Roku and DAAP clients
-#                    iTunes. It can also stream music to AirTunes devices.
+#                    like iTunes. It can also stream music to AirTunes devices, 
+#                    and it can be controlled by Apple Remote (and compatibles).
 ### END INIT INFO

NEWS

@@ -1,5 +0,0 @@
-forked-daapd NEWS
------------------
-
-version 0.10:
-	It's released, and that's news. Yup.

README

@@ -32,26 +32,36 @@ or RSP.
 A single forked-daapd instance can handle several clients concurrently,
 regardless of the protocol.
 
+forked-daapd support streaming to AirTunes devices (like the AirPort Express,
+Shairport and various AirPlay speakers).
+
+Like iTunes, you can control forked-daapd with Apple Remote, or with a 
+compatible Android app like Retune, TunesRemote+ or Hyperfine Remote. Another
+controller is TunesRemoteSE, which is based on Java and runs in Windows, MacOS
+and Linux.
+
 
 Using Remote
 ------------
 
 If you plan to use Remote with forked-daapd, read the following sections
-carefully.
+carefully. The pairing process described is similar for other controllers, but
+some do not require pairing.
 
   Pairing with Remote on iPod/iPhone
   ----------------------------------
 
-forked-daapd can be paired with Apple's Remote application for iPod/iPhone;
+forked-daapd can be paired with Apple's Remote application for iPod/iPhone/iPad;
 this is how the pairing process works:
+
  - start forked-daapd
- - start Remote, go to Choose Library, Add Library
+ - start Remote, go to Settings, Add Library
  - prepare a text file with a filename ending with .remote; the filename
    doesn't matter, only the .remote ending does. This file must contain
-   two lines: the first line is the name of your iPod/iPhone, the second
+   two lines: the first line is the name of your iPod/iPhone/iPad, the second
    is the 4-digit pairing code displayed by Remote.
 
-   If your iPod/iPhone is named "Foobar" and Remote gives you the pairing
+   If your iPod/iPhone/iPad is named "Foobar" and Remote gives you the pairing
    code 5387, the file content will be:
 
       Foobar
@@ -74,10 +84,10 @@ receives the mDNS announcement from your iPod/iPhone when the pairing code is
 displayed by Remote (you can also use avahi-browse for this purpose, see below).
 If not, you have a network issue and mDNS doesn't work properly on your network.
 
-If you are unsure about your iPod/iPhone's name, here's how you can check for
+If you are unsure about your iPod/iPhone/iPad's name, here's how you can check
-the correct value:
+for the correct value:
  - in a terminal, run avahi-browse -r -k _touch-remote._tcp
- - start Remote, goto Choose Library, Add Library
+ - start Remote, goto Settings, Add Library
  - after a couple seconds at most, you should get something similar to this:
 
 + ath0 IPv4 59eff13ea2f98dbbef6c162f9df71b784a3ef9a3      _touch-remote._tcp   local
@@ -87,7 +97,7 @@ the correct value:
    port = [49160]
    txt = ["DvTy=iPod touch" "RemN=Remote" "txtvers=1" "RemV=10000" "Pair=FAEA410630AEC05E" "DvNm=Foobar"]
 
-The name of your iPod/iPhone is the value of the DvNm field above. In this
+The name of your iPod/iPhone/iPad is the value of the DvNm field above. In this
 example, the correct value is Foobar.
 
 Watch out for fancy characters; for instance, the name of your device may
@@ -112,13 +122,6 @@ selecting an output device at random that can be anywhere in the house or
 elsewhere). forked-daapd will error out if the local output is not usable
 (no soundcard, bad permissions, ...).
 
-There are two ways to select the output devices in Remote:
- - in the settings panel;
- - in the AirPlay panel during playback.
-
-Be aware that the settings panel doesn't show any output device when there
-is only one; the one output device that is available is automatically used.
-
 forked-daapd remembers your selection and the individual volume for each
 output device; selected devices will be automatically re-selected at the next
 server startup, provided they appear in the 5 minutes following the startup
@@ -152,10 +155,6 @@ forked-daapd should support pretty much all media formats. It relies on libav
 (ffmpeg) to extract metadata and decode the files on the fly when the client
 doesn't support the format.
 
-However, libav is not necessarily very good at extracting metadata, so some
-formats may cause problems. FLAC, Musepack and WMA use custom metadata
-extractors to work around that.
-
 Formats are attributed a code, so any new format will need to be explicitely
 added. Currently supported:
  - MPEG4: mp4a, mp4v
@@ -263,6 +262,16 @@ playlists from forked-daapd's database and initiate a fresh bulk scan. Pairing
 and speaker information will be kept. Only use this for troubleshooting, it is
 not necessary during normal operation.
 
+A full rescan might take some time, and sometimes you just want a rescan of a
+particular part of your library. In this case the standard "touch" command is
+very usefull, as it will update the timestamps of the arguments and thus trigger
+a rescan.
+
+If you change any of the directory settings in the library section of the
+configuration file a rescan is required before the new setting will take effect.
+Currently, this will not be done automatically, so you need to trigger the
+rescan as described above.
+
 Symlinks are supported and dereferenced. This does interact in tricky ways
 with the above monitoring and rescanning, so you've been warned. Changes to
 symlinks themselves won't be taken into account, or not the way you'd expect.