further docs fettling

diff --git a/README b/README
index b61ac7a22252301c028043ad4de9b189c355c377..ff6345b1c5d9de184a53a79307beba3e2391719f 100644 (file)
--- a/README
+++ b/README
@@ -15,9 +15,9 @@ DisOrder is a multi-user software jukebox.
 
 See CHANGES for details of recent changes to DisOrder.
 
 
 See CHANGES for details of recent changes to DisOrder.
 

-The server supports Linux and can be made to on a Mac (see README.mac).  The
-clients work on both Linux and the Mac.  It could probably be ported to some
-other UNIX variants without too much effort.  Things you will need:
+The server supports Linux and can be made to work on a Mac (see README.mac).
+The clients work on both Linux and the Mac.  It could probably be ported to
+some other UNIX variants without too much effort.  Things you will need:

 
 Build dependencies:
   Name             Tested              Notes
 
 Build dependencies:
   Name             Tested              Notes


@@ -73,6 +73,9 @@ Installation
 
 NOTE: If you are upgrading from an earlier version, see README.upgrades.
 
 
 NOTE: If you are upgrading from an earlier version, see README.upgrades.
 

+On a Debian system, if you install from .deb files then you should be able to
+skip steps 1 to 6 and configure it via debconf.  This is strongly recommended!
+

 1. Build the software.  Do something like this:
 
      ./configure --sysconfdir=/etc --localstatedir=/var
 1. Build the software.  Do something like this:
 
      ./configure --sysconfdir=/etc --localstatedir=/var


@@ -145,13 +148,15 @@ NOTE: If you are upgrading from an earlier version, see README.upgrades.
    start up correctly there should be an error message.  Correct the problem
    and try again.
 
    start up correctly there should be an error message.  Correct the problem
    and try again.
 

-7. After a minute it should start to play something.  Try scratching it:
+7. After a minute it should start to play something.  Try scratching it (as
+   root):

 
      disorder scratch
 
    The track should stop playing, and (if you set any up) a scratch sound play.
 
 
      disorder scratch
 
    The track should stop playing, and (if you set any up) a scratch sound play.
 

-8. Add any other users you want.  These easiest way to do this is:
+8. Add any other users you want.  These easiest way to do this is (still as
+   root):

 
      disorder authorize USERNAME
 
 
      disorder authorize USERNAME
 

diff --git a/README.streams b/README.streams
index 0a2676ce0b20cb74d6886d415074df3fb61aa296..9fe3e3af82de02220ed7f793a7a497c2405e698c 100644 (file)
--- a/README.streams
+++ b/README.streams
@@ -1,7 +1,7 @@
 * Introduction
 
 * Introduction
 

-This file describes DisOrder's relationship to various things that get called
-'streams'.
+This file describes DisOrder's relationship to several different things that
+get called 'streams'.

 
 * RTP Streaming
 
 
 * RTP Streaming
 


@@ -18,24 +18,26 @@ backend:
     broadcast_from 172.17.207.2 9002
 
 The destination address (broadcast) can be:
     broadcast_from 172.17.207.2 9002
 
 The destination address (broadcast) can be:

-   - a unicast address if you only want to talk to one client

    - a broadcast address for a local network
    - a multicast address
 
    - a broadcast address for a local network
    - a multicast address
 

-The source address (broadcast_from) is optional but may be convenient in som
-ecases.
+The source address (broadcast_from) is optional but may be convenient in some
+cases.

 
 If the destination is a multicast address then you should set the TTL, for
 instance:
 
    multicast_ttl 10
 
 
 If the destination is a multicast address then you should set the TTL, for
 instance:
 
    multicast_ttl 10
 

+(The destination can also be a unicast address but that's not a tested
+configuration.)
+

 ** Playing The Stream
 
 To play, use the disorder-playrtp client.  If the destination address was a
 unicast or broadcast address then:
 
 ** Playing The Stream
 
 To play, use the disorder-playrtp client.  If the destination address was a
 unicast or broadcast address then:
 

-   disorder-playrtp 0.0.0.0 9003
+   disorder-playrtp 9003

 
 If the destination address was a multicast address then you must specify that,
 for instance:
 
 If the destination address was a multicast address then you must specify that,
 for instance:


@@ -53,7 +55,7 @@ it is installed); look for the speaker icon.  If it detects that the server is
 using network play then its volume control will apply to the local volume, not
 the server's volume.
 
 using network play then its volume control will apply to the local volume, not
 the server's volume.
 

-If you run into trouble look for *.log files in ~/.disorder.
+If you run into trouble look for *.log files in the ~/.disorder directory.

 
 ** Limitations
 
 
 ** Limitations
 


@@ -65,7 +67,7 @@ any success with wireless.
 Possibly other lower-quality but lower-bandwidth encodings will be supported in
 future.
 
 Possibly other lower-quality but lower-bandwidth encodings will be supported in
 future.
 

-If you have a too-recent version of sox you may need to set the sox_generation
+If you have a very recent version of sox you may need to set the sox_generation

 option.  See disorder_config(5).
 
 
 option.  See disorder_config(5).
 
 


@@ -89,35 +91,34 @@ where ices.xml is:
       <loglevel>4</loglevel>
       <consolelog>0</consolelog>
       <stream>
       <loglevel>4</loglevel>
       <consolelog>0</consolelog>
       <stream>

-         <metadata>
-             <name>lyonesse</name>
-             <genre>Various</genre>
-             <description>lyonesse disorder output</description>
-         </metadata>
-         <input>
-             <module>stdinpcm</module>
-             <param name="rate">44100</param>
-             <param name="channels">2</param>
-             <param name="metadata">1</param>
-             <param name="metadatafilename">/var/disorder/icedata</param>
-         </input>
-         <instance>
-             <hostname>lyonesse.anjou.terraraq.org.uk</hostname>
-             <port>8000</port>
-             <password>SOURCE PASSWORD HERE</password>
-             <mount>/disorder.ogg</mount>
-             <reconnectdelay>2</reconnectdelay>
-             <reconnectattempts>5</reconnectattempts>
-             <maxqueuelength>80</maxqueuelength>
-             <encode>
-                 <nominal-bitrate>64000</nominal-bitrate>
-                 <samplerate>44100</samplerate>
-                 <channels>2</channels>
-                 <flush-samples>8820</flush-samples>
-             </encode>
-         </instance>
-
-         </stream>
+          <metadata>
+              <name>lyonesse</name>
+              <genre>Various</genre>
+              <description>lyonesse disorder output</description>
+          </metadata>
+          <input>
+              <module>stdinpcm</module>
+              <param name="rate">44100</param>
+              <param name="channels">2</param>
+              <param name="metadata">1</param>
+              <param name="metadatafilename">/var/disorder/icedata</param>
+          </input>
+          <instance>
+              <hostname>lyonesse.anjou.terraraq.org.uk</hostname>
+              <port>8000</port>
+              <password>SOURCE PASSWORD HERE</password>
+              <mount>/disorder.ogg</mount>
+              <reconnectdelay>2</reconnectdelay>
+              <reconnectattempts>5</reconnectattempts>
+              <maxqueuelength>80</maxqueuelength>
+              <encode>
+                  <nominal-bitrate>64000</nominal-bitrate>
+                  <samplerate>44100</samplerate>
+                  <channels>2</channels>
+                  <flush-samples>8820</flush-samples>
+              </encode>
+          </instance>
+      </stream>

   </ices>
 
 This doesn't seem to get on very well with pausing but you're unlikely to want
   </ices>
 
 This doesn't seem to get on very well with pausing but you're unlikely to want


@@ -128,6 +129,9 @@ behind the 'current' time, watch this space for a fix (or contribute one!)
 If you have a too-recent version of sox you may need to set the sox_generation
 option.
 
 If you have a too-recent version of sox you may need to set the sox_generation
 option.
 

+Mark Wooding contributed the original support for this but it's been modified
+enough that he probably shouldn't be blamed for any bugs in the current code.
+

 
 * DisOrder and Republishing Internet Streams
 
 
 * DisOrder and Republishing Internet Streams
 

diff --git a/README.upgrades b/README.upgrades
index a79767b0108f9b39a938ede9d2816ab68d4a177d..915a79416593eb266cc727dadbce86aa7c5db5f5 100644 (file)
--- a/README.upgrades
+++ b/README.upgrades
@@ -2,9 +2,8 @@
 
 The general procedure is:
 
 
 The general procedure is:
 

- * stop the old daemon, e.g. with
-     /etc/init.d/disorder stop
- * back up your database
+ * stop the old daemon:  /etc/init.d/disorder stop
+ * back up your database directory (example below)

  * build and install the new version as described in the README
  * update the configuration files (see below)
  * start the new daemon, e.g. with
  * build and install the new version as described in the README
  * update the configuration files (see below)
  * start the new daemon, e.g. with


@@ -15,15 +14,28 @@ upgrading between particular versions.  Minor versions are not
 explicitly mentioned; a version number like 1.1 implicitly includes
 all 1.1.x versions.
 
 explicitly mentioned; a version number like 1.1 implicitly includes
 all 1.1.x versions.
 

-* 1.5 -> 2.0
+* 1.4/1.5 -> 2.0

 
 

-** Database upgrade
+** 'transform' and 'namepart' directives

 
 

-The first thing the server does when upgrading from 1.5 is run the
-disorder-dbupgrade program.  This is necessary to modify any non-ASCII track
-names to meet the latest version's stricter normalization practices.  The
-upgrade should succeed automatically; if not it should leave an error message
-in syslog.
+'transform' has moved from the web options to the main configuration file, so
+that they can be used by other interfaces.  The syntax and semantics are
+unchanged.
+
+More importantly however both 'transform' and 'namepart' are now optional, with
+sensible defaults being built in.  So if you were already using the default
+values you can just delete all instances of both.
+
+See disorder_config(5) for the default values.  Hopefuly they will be suitable
+for many configurations.  Please do send feedback.
+
+** 'enabled' and 'random_enabled' directives
+
+These have been removed.  Instead the state persists from one run of the server
+to the next.  If they appear in your configuration file they must be removed;
+the server will not start if they are present.
+
+** Database upgrade

 
 It is strongly recommended that you back up your database before performing the
 upgrade.  For example, as root, with the server STOPPED:
 
 It is strongly recommended that you back up your database before performing the
 upgrade.  For example, as root, with the server STOPPED:


@@ -36,20 +48,11 @@ To restore, again as root:
   rm *
   cp -p BACKUP/* .
 
   rm *
   cp -p BACKUP/* .
 

-** 'transform' and 'namepart' directives
-
-'transform' has moved from the web options to the main configuration file, so
-that they can be used by other interfaces.  The syntax and semantics are
-unchanged.
-
-More importantly however both 'transform' and 'namepart' are now optional, with
-sensible defaults being built in.  So if you were already using the default
-values you can just delete all instances of both.
-
-** enabled' and 'random_enabled' directives
-
-These have been removed.  Instead the state persists from one run of the server
-to the next.
+The first thing the server does when upgrading from 1.5 is run the
+disorder-dbupgrade program.  This is necessary to modify any non-ASCII track
+names to meet the latest version's stricter normalization practices.  The
+upgrade should succeed automatically; if not it should leave an error message
+in syslog.

 
 * 1.3 -> 1.4
 
 
 * 1.3 -> 1.4