README.afs: Minor improvments and clarifications.

diff --git a/README.afs b/README.afs
index d77f6bfa39a84fdb35304f1f55d4344d7160ba86..9e588a6a6c7a888168bf61af239823e81c98f560 100644 (file)
--- a/README.afs
+++ b/README.afs
@@ -1,7 +1,7 @@
 The audio file selector
 =======================
 
-Paraslash comes with a sophisticated audio file selector called afs.
+Paraslash comes with a sophisticated audio file selector called *afs*.
 In the
 <<
 <a href="INSTALL.html">installation notes</a>,
@@ -31,12 +31,12 @@ an audio file by executing
 
        para_client setatt test+ /path/to/the/audio/file
 
-Similarly, the "test" bit can be removed from a audio file with
+Similarly, the "test" bit can be removed from an audio file with
 
        para_client setatt test- /path/to/the/audio/file
 
-Instead of a path you can also use a pattern, and the attribute is
-applied to all audio files matching that pattern:
+Instead of a path you may use a shell wildcard pattern. The attribute
+is applied to all audio files matching that pattern:
 
        para_client setatt test+ '/test/directory/*'
 
@@ -53,9 +53,9 @@ you find this annoying, just say
 
        alias para='para_client --'
 
-and be happy. In the remainder part this alias is being used.
+and be happy. In what follows we shall use this alias.
 
-Drop the test attribute entirely from the database with
+The "test" attribute can be dropped from the database with
 
        para rmatt test
 
@@ -74,13 +74,14 @@ Abstract mood nonsense
 
 [skip this part if you don't like formal definitions]
 
-A mood consists of a unique name and its *mood definition*, which is a set of
-*mood lines* containing expressions in terms of attributes and other data
-contained in the database.
+A mood consists of a unique name and its *mood definition*, which is
+a set of *mood lines* containing expressions in terms of attributes
+and other data contained in the database.
 
-A mood defines a subset of audio files called the *admissible audio files*
-for that mood. A mood can be *active* which means that para_server
-is going to select only files from that subset of admissible files.
+A mood defines a subset of audio files called the *admissible audio
+files* for that mood. At any time, at most one mood can be *active*
+which means that para_server is going to select only files from that
+subset of admissible files.
 
 So in order to create a mood definition one has to write a set of
 mood lines. Mood lines come in three flavours: Accept lines, deny
@@ -99,7 +100,7 @@ a random score to all matching files. The score value changes the
 order in which admissible files are going to be selected, but is of
 minor importance for this introduction.
 
-So we concentrate on the first two forms, that is accept and deny
+So we concentrate on the first two forms, i.e. accept and deny
 lines. As usual, everything in square brackets is optional, i.e.
 accept/deny lines take the following form when ignoring scores:
 
@@ -121,12 +122,12 @@ or
 
 The set of admissible files for the whole mood is now defined as those
 files which match at least one accept mood line, but no deny mood line.
-More formally, a file is admissible if and only if
+More formally, an audio file F is admissible if and only if
 
        (F ~ AL1 or F ~ AL2...) and not (F ~ DL1 or F ~ DN2 ...)
 
-where F is the file, AL1, AL2... are the accept lines, DL1, DL2... are
-the deny lines and "~" means "matches".
+where AL1, AL2... are the accept lines, DL1, DL2... are the deny
+lines and "~" means "matches".
 
 The cases where no mood lines of accept/deny type are defined need
 special treatment:
@@ -192,7 +193,7 @@ the catmood command to get it back:
 
 A mood can be activated by executing
 
-       para chmood my_mood
+       para select m/my_mood
 
 Once active, the list of admissible files is shown by the ls command
 if the "-a" switch is given:
@@ -226,14 +227,14 @@ Troubles?
 
 Use loglevel one (option -l 1 for most commands) to show debugging
 info. Almost all paraslash executables have a brief online help which
-is displayed by using the -h switch.
+is displayed by using the -h switch. The --detailed-help option prints
+the full help text.
 
 para_fsck tries to fix your database. Use --force (even if your name
-isn't Luke), to clean up after a crash. However, first make sure
+isn't Luke) to clean up after a crash. However, first make sure
 para_server isn't running before executing para_fsck if para_fsck
 complains about busy (dirty) tables. para_fsck also contains an option
-to dump the contents of your the contents of the database to the file
-system.
+to dump the contents of the database to the file system.
 
 If you don't mind to recreate your database you can start
 from scratch by removing the entire database directory, i.e.