Formatting beautified

git-svn-id: https://vdr-muggle.svn.sourceforge.net/svnroot/vdr-muggle/trunk/muggle-plugin@383 e10066b5-e1e2-0310-b819-94efdf66514b

1 files changed, 131 insertions, 47 deletions

diff --git a/README b/README
index ea2046f..06e0064 100644
--- a/README
+++ b/README
@@ -1,6 +1,6 @@
 /*! \mainpage Muggle: Media Juggler for VDR
 
-This is a "plugin" for the Video Disk Recorder (VDR).
+This is a plugin for the Video Disk Recorder (VDR).
 
 Written by:                  Andi Kellner,
                              Lars von Wedel <vonwedel@web.de>,
@@ -34,8 +34,8 @@ parameters are descibed in Section 5.
 
 \section prereq PREREQUISITES
 
-The plugin currently runs on VDR 1.3.7+. In addition, the following pieces of 
-software are required:
+The plugin currently runs on versions 1.3.17- of VDR. It also compiles on 1.3.18 but
+your mileage may vary. In addition, the following pieces of software are required:
 
  - mySQL server (tested with 4.0.18) (Debian packages mysql-server, mysql-client)
  - mySQL client libraries
@@ -63,13 +63,13 @@ For example (paths and version numbers may vary)
 
 \verbatim
    cd /usr/local/src/VDR/PLUGINS/src
-   tar xvjf muggle-0.1.7.tar.bz2
+   tar xvjf muggle-0.1.1.tgz
 \endverbatim
 
 Establish a symlink as you would for other plugins:
 
 \verbatim
-   ln -s muggle-0.1.0 muggle
+   ln -s muggle-0.1.1 muggle
 \endverbatim
 
 Within the VDR main directory (e.g. /usr/local/src/VDR) issue
@@ -192,63 +192,116 @@ If a track has no ID3 tags, the following defaults will be applied:
 
 \section config MUGGLE CONFIGURATION
 
-Muggle uses a small set of command line parameters in order to control the interaction with the mySQL server.
-Let's look at an example:
+Muggle uses a small set of command line parameters in order to control 
+the interaction with the mySQL server. Let's look at an example:
 
 \verbatim
   -P'muggle -h localhost -u vdr -n GiantDisc -t/home/music'
 \endverbatim
 
-The -h parameter specifies the database host, -u specifies the user, -n is the database name. The scripts mentioned
-above do not make use of passwords, but restrict database acccess on a server basis. 
+The -h parameter specifies the database host, -u specifies the user,
+-n is the database name. The scripts mentioned above do not make use
+of passwords, but restrict database acccess on a server basis. 
 
-The -t argument specifies the top level directory of the music files. On a local installation, this is the
-directory in which you executed the import steps (Chapter 4.2).
+The -t argument specifies the top level directory of the music files. 
+On a local installation, this is the directory in which you executed the
+import steps (Chapter 4.2).
 
 \section quickuse QUICK INTRO
 
-Quick version: select Muggle on the OSD, browse titles (using up/down and Ok), add them using the red button.
-Music will start instantly while you can continue to browse and add tracks.
+Quick version: select Muggle on the OSD, browse titles (using up/down and Ok),
+add them using the red button. Music will start instantly while you can continue
+to browse and add tracks.
 
-During playback, Up/Down jumps forth and back in the current playlist. Yellow toggles play/pause mode and Ok
-toggles a display of the replay process. Using Green, the display can be switched between playlist and single display mode, red toggles info and progress view. For VDR 1.3.6- the progress display is "quite simple", unfortunately.
+During playback, Up/Down jumps forth and back in the current playlist. Yellow 
+toggles play/pause mode and Ok toggles a display of the replay process. Using
+Green, the display can be switched between playlist and single display mode,
+Red toggles info and progress view. For VDR 1.3.6- the progress display is
+"quite simple", unfortunately.
 
 \section use DETAILED USER'S GUIDE
 
-The core concept of the Muggle user interface is called a *selection*. That is, as the name suggests, a selection of music tracks. Note, that a selection can be as small as a single track (a very simple selection, indeed) or as large as the whole music library.
-
-Selections are used to structure all tracks (the music library) into sets (e.g. a selection of all tracks by an author) and subsets (e.g. the tracks of an author on a certain album). Such selections are built by means of keys (e.g. author or album) defined in the database and are displayed in the *music browser*. The current selection in the *music browser* contains all tracks defined by the line the cursor is on. So if you place the cursor on the line "Pop", all tracks with Genre Pop are selected. If you then enter Pop and go to the line "Beatles", you narrow your selection to pop songs from the beatles.
-
-A collection is a special selection. Collections can be defined by the user, and he can add or remove any selection to / from a collection. A collection has only ony order: a number which is incremented for every added track. Otherwise, since a collection is also a selection, everything that is valid for selections also holds for collections.
-
-Collections can be defined by the user in the sense of a playlist. This is done by adding/removing selections to/from the *default collection*.
-
-Changing the contents of a collection changes them directly in the data base. Saving or loading collections is not needed.
-
-A very important term while working with Muggle is the *default collection*. This is a special collection which is the target of commands working on collections. Whenever you add selections to somewhere, they will be added to the default collection. The same happens when you remove selections.
-
-Another important collection is the 'play' collection. This is a temporary collection. Whatever is added to it will be played in that order. If you add something while muggle is not playing anything, this collection will first be emptied.
-However 'temporary' does not mean that its content is not saved to the data base. 
+The core concept of the Muggle user interface is called a *selection*. That is,
+as the name suggests, a selection of music tracks. Note, that a selection can be
+as small as a single track (a very simple selection, indeed) or as large as the
+whole music library.
+
+Selections are used to structure all tracks (the music library) into sets (e.g. 
+a selection of all tracks by an author) and subsets (e.g. the tracks of an author 
+on a certain album). Such selections are built by means of keys (e.g. author 
+or album) defined in the database and are displayed in the *music browser*. The
+current selection in the *music browser* contains all tracks defined by the line 
+the cursor is on. So if you place the cursor on the line "Pop", all tracks with
+Genre Pop are selected. If you then enter Pop and go to the line "Beatles", you
+narrow your selection to pop songs from the beatles.
+
+A collection is a special selection. Collections can be defined by the user, and 
+he can add or remove any selection to / from a collection. A collection has only 
+one order: a number which is incremented for every added track. Otherwise, since 
+a collection is also a selection, everything that is valid for selections also 
+holds for collections.
+
+Collections can be defined by the user in the sense of a playlist. This is done by
+adding/removing selections to/from the *default collection*.
+
+Changing the contents of a collection changes them directly in the data base. Saving
+or loading collections is not needed.
+
+An important term while working with Muggle is the *default collection*. This 
+is a special collection which is the target of commands working on collections.
+Whenever you add selections to somewhere, they will be added to the default
+collection. The same happens when you remove selections.
+
+Another important collection is the 'play' collection. This is a temporary collection.
+Whatever is added to it will be played in that order. If you add something while muggle
+is not playing anything, this collection will first be emptied. However 'temporary' does
+not mean that its content is not saved to the data base. 
+
+Starting from release 0.1.1 Muggle can be also used without default playlists. There are 
+new menu entries "Add X to collection" and "Remove X from collection" which show a list
+of all collections to choose from. The concept of a default collection still exists and
+both approaches can be used in common. However, you can spceify which commands to use for
+the special keys Red/Green/Blueas you like.
 
 \subsection general General remarks
 
-There are two main views in Muggle, the *Music browser* view and the *Collection browser* view. You can toggle between them using the yellow key.
+There are two main views in Muggle, the *Music browser* view and the *Collection browser*
+view. You can toggle between them using the Yellow key by default, however the key binding
+can be changed.
 
-Each of the two views has associated commands. To show a summary of the commands available for the current view press the blue key. Note, that the red, green and yellow keys do not have a fixed meaning. Rather, while the commands for a certain view are displayed, you can press red/green/yellow to make the respective key execute the command currently selected (highlighted) by the cursor. The commands you choose for red/green/yellow will be saved for the next time you start muggle. You can define different commands in both view *Music browser* and *Collection browser*.
+Each of the two views has associated commands. To show a summary of the commands available
+for the current view press the blue key. Note, that the red, green and yellow keys do not
+have a fixed meaning. Rather, while the commands for a certain view are displayed, you can
+press red/green/yellow to make the respective key execute the command currently selected
+(highlighted) by the cursor. The commands you choose for red/green/yellow will be saved for
+the next time you start muggle. You can define different commands in both view *Music browser*
+and *Collection browser*.
 
 \subsection browse Music browser
 
-By default, Muggle starts in the *Music browser* display at the place where you left it last time. This browser displays the music library according to a search order, e.g. according to artists / albums / tracks or genre / year / track. These search orders are currently fixed in the code, but the objective is to make them editable by the user on the OSD. Browsing these search orders is done using Up/Down/Left/Right keys. To display the contents of a currently selected selection, press Ok. To return to the parent selection press Back.
+By default, Muggle starts in the *Music browser* display at the place where you left it 
+last time. This browser displays the music library according to a search order, e.g. 
+according to artists / albums / tracks or genre / year / track. These search orders are 
+currently fixed in the code, but the objective is to make them editable by the user on the 
+OSD. Browsing these search orders is done using Up/Down/Left/Right keys. To display the 
+contents of a currently selected selection, press Ok. To return to the parent selection 
+press Back.
 
-A set of commands can be displayed with the Blue key on the remote control. A new menu will open and show the commands explained below. Remember that pressing Red, Green or Yellow will make these keys execute the command currently highlighted by the cursor from now on.
+A set of commands can be displayed with the Blue key on the remote control. A new menu 
+will open and show the commands explained below. Remember that pressing Red, Green or 
+Yellow will make these keys execute the command currently highlighted by the cursor 
+from now on.
 
 Those commands are currently available in the *music browser*:
 
 - Instant Play: instantly play the current selection. This does not enter any collection.
 
-- Add to 'play': add the current selection to the default collection. After the first start of muggle, the default collection is 'play'
+- Add to 'play': add the current selection to the default collection. After the first 
+start of Muggle, the default collection is 'play'
 
-- Remove from 'play': remove the current selection from the default collection. If there are more than one instances of a specific track in the collection, they are all removed.
+- Remove from 'play': remove the current selection from the default collection. If 
+there are more than one instances of a specific track in the collection, they are all 
+removed.
 
 - Collections: switch to the collection view
 
@@ -258,17 +311,32 @@ Those commands are currently available in the *music browser*:
 
 - External commands: whatever you define
 
-By default, the red key adds the currently selected collection to the default collection. The green key instantly plays the currently selected collection. The yellow key toggles between the *Music browser* and the *Collection browser*. Thus, if you want to play an album, browse to it and press green. Remember that you can redefine commands executed by red, green and yellow by pressing them while displaying the command list.
+By default, the red key adds the currently selected collection to the default collection. 
+The green key instantly plays the currently selected collection. The yellow key toggles
+between the *Music browser* and the *Collection browser*. Thus, if you want to play an
+album, browse to it and press green. Remember that you can redefine commands executed by 
+Red, Green and Yellow by pressing them while displaying the command list.
 
 \subsection collections Collection browser
 
-The *Collection browser* displays a list of available collections. Browse the list with Up/Down and display the collection contents with Ok. Returning to the collection list is done by pressing Back. One of the collections (the one called "play" when you start up muggle for the first time) is marked with a "->" in front of the name, meaning that it is the default collection. Whenever you add or remove selections, this default collection is the current target, meaning that selections will be added/removed to/from this collection.
+The *Collection browser* displays a list of available collections. Browse the list with 
+Up/Down and display the collection contents with Ok. Returning to the collection list 
+is done by pressing Back. One of the collections (the one called "play" when you start
+up Muggle for the first time) is marked with a "->" in front of the name, meaning that
+it is the default collection. Whenever you add or remove selections, this default 
+collection is the current target, meaning that selections will be added/removed 
+to/from this collection.
 
-At the bottom of the list, the entry "Create collection" is displayed. Entering it with the right key will make the editor appear on the second half of the line and using the keys Up/Down/Left/Right you can enter the name of the new collection. Pressing Ok will terminate the editing process and add the new collection to the list. 
+At the bottom of the list, the entry "Create collection" is displayed. Entering it with 
+the right key will make the editor appear on the second half of the line and using the 
+keys Up/Down/Left/Right you can enter the name of the new collection. Pressing Ok will 
+terminate the editing process and add the new collection to the list. 
 
-Just like with the *music browser*, a set of commands can be displayed with the Blue key on the remote control. 
+Just like with the *music browser*, a set of commands can be displayed with the Blue 
+key on the remote control. 
 
-Those commands are currently available in the list of collections. Depending on the current selection, not all of them are available:
+Those commands are currently available in the list of collections. Depending on the
+current selection, not all of them are available:
 
 - Instant play: See *music browser*
 
@@ -288,12 +356,28 @@ Those commands are currently available in the list of collections. Depending on
 
 - External commands: whatever you define
 
-Note that you cannot only add to/remove from collections in the *music browser*. Rather, also collections can be added/removed. The reason is that - as explained above - a collection is also a selection. So everything that can be done with selections can also be done with collections. An example: if you want to give a party, you could create a new collection "Party". Now, steer your cursor to the collection entitled "Lounge music" and select add. Then go to "Pop 80s" and add again. Finally, go to "Dance classics" and add. Now you have created a collection "Party" from three already existing collections. To continue this example, let us assume that one of your guests has a personal dislike against "Modern Talking". Switch to the browser view, go to the artist selection of "Modern Talking" and select "Remove". Now all tracks written by Modern Talking will be removed from your "Party" collection.
-
-Please note that "Remove" means removing from the default collection. "Delete" will delete a collection.
-
-It is possible that a collection holds the same track several times if you add it several times. However when you remove that track, all of its occurrences will be removed.
-
-The remote buttons Play, Pause, Stop are also supported while muggle displays its OSD. If Stop is pressed, muggle first stops playing what was started by Instant Play. Muggle will then continue playing the 'play' collection. A second Stop will stop playing the 'play' collection.
+Note that you cannot only add to/remove from collections in the *music browser*.
+Rather, also collections can be added/removed. The reason is that - as explained 
+above - a collection is also a selection. So everything that can be done with
+selections can also be done with collections. An example: if you want to give a
+party, you could create a new collection "Party". Now, steer your cursor to the 
+collection entitled "Lounge music" and select add. Then go to "Pop 80s" and add 
+again. Finally, go to "Dance classics" and add. Now you have created a collection 
+"Party" from three already existing collections. To continue this example, let us 
+assume that one of your guests has a personal dislike against "Modern Talking". 
+Switch to the browser view, go to the artist selection of "Modern Talking" and 
+select "Remove". Now all tracks written by Modern Talking will be removed from 
+your "Party" collection.
+
+Please note that "Remove" means removing from the default collection. "Delete" will 
+delete a collection.
+
+It is possible that a collection holds the same track several times if you add it 
+several times. However when you remove that track, all of its occurrences will be removed.
+
+The remote buttons Play, Pause, Stop are also supported while muggle displays its 
+OSD. If Stop is pressed, muggle first stops playing what was started by Instant 
+Play. Muggle will then continue playing the 'play' collection. A second Stop will 
+stop playing the 'play' collection.
 
 */