Some corrections in documentation. Preparation for 0.2. Release 0.2

README

@@ -52,6 +52,13 @@ For more information on usage see the man page shoutcast-search(1) or:
 
 Changes
 -------
+0.2 (2009-04-12):
+     --sorted option.
+     exit code 4 when no stations found
+     documentation.md (in markdown format)
+     minor corrections in e.g. man page
+
+
 0.1 (2009-04-08):
      First release. Packaged as application, even though the source code
      is fairly prepared to be used as a python module.

build_release.sh

@@ -14,6 +14,7 @@ cat config.mk | sed s/CURVERSION/$1/g > $RELEASENAME/config.mk
 cat Makefile | sed s/CURVERSION/$1/g > $RELEASENAME/Makefile
 cat shoutcast-search | sed s/CURVERSION/$1/g > $RELEASENAME/shoutcast-search
 cat shoutcast-search.1 | sed s/CURVERSION/$1/g > $RELEASENAME/shoutcast-search.1
+cat documentation.md | sed s/CURVERSION/$1/g > $RELEASENAME/documentation.md
 
 tar cvzf releases/${RELEASENAME}.tar.gz $RELEASENAME
 

documentation.md

@@ -1,19 +1,23 @@
 # shoutcast-search
 
-shoutcast-search searches the [shoutcast.com](http://www.shoutcast.com) radio stations from your command line. 
+shoutcast-search searches the [shoutcast.com](http://www.shoutcast.com) radio stations from your command line. It is developed and tested on Linux, but since it is written in Python it may run, or at least should be easily portable, to other operating systems.
 
-* [man page](http://www.k2h.se/code/shoutcast-search-0.1.man.html)
-* [latest release](http://www.k2h.se/code/dl/shoutcast-search-0.1.tar.gz)
+* [man page](http://www.k2h.se/code/shoutcast-search.man.txt)
+* [latest release](http://www.k2h.se/code/dl/shoutcast-search-latest.tar.gz)
 * [source repository](http://github.com/halhen/shoutcast-search/tree/master)
 
+Distribution specific links:
+
+* [archlinux AUR package](http://aur.archlinux.org/packages.php?ID=25366)
+
 ## Why shoutcast-search?  
 
 * More powerful searches than at shoutcast.com.
 * Handy - only a terminal window away.
 * Automation.
 
 ## Automatic station selection
-In default mode, shoutcast-search prints the URLs of the matching radio station, with one URL per line. These lines can be fed to a media player which will start playing the selected tracks. For example, to play a random Top 500 station in VLC.
+In default mode, shoutcast-search prints the URLs of the matching radio station, with one URL per line. These lines can be fed to a media player which will start playing the selected tracks. To play a random Top 500 station in VLC for example:
 
 	$ shoutcast-search -n 1 -r | xargs vlc &
 
@@ -23,12 +27,12 @@ shoutcast-search can also be run in verbose mode: `shoutcast-search -v`. This is
 * To adjust the search  
   Getting the search can be a little tricky. shoutcast-search prints debug information about the search to help you get it right.
 
-* To manually cho0se between the stations.  
+* To manually choose between the stations.  
   In verbose mode, the stations are listed with more information. This allows you to browse the hits and manually copy the URL for whatever station you want to listen to.
 
-An example of verbose output is listed below.
+An example of verbose output:
 
-    $ shoutcast-search --verbose --limit=2 --random --genre=ambient
+    $ shoutcast-search --verbose --sort=rn2l --genre=ambient
     Search summary
     ------------------------------
     Keywords:
@@ -38,8 +42,8 @@ An example of verbose output is listed below.
      Bitrate:
    Listeners:
         Type:
-       Order: random
-      Manips:
+       Order: by sorters
+      Sorter: random order | top 2 | listeners desc
        Limit: 2
 
    Bluemars - Music for the Space Traveler [128kbps audio/mpeg]
@@ -68,17 +72,15 @@ You can perform free-text searches on three pieces of information
 * Song (`-p`)
 * Station (`-s`)
 
-The stations are responsible for this information, usually they match pretty well. The picture below shows which strings are search for each parameter (screenshot from <http://www.shoutcast.com>). You can search for several criteria at once. All criteria must match for a station to be listed. For example searching `shoutcast-search -g synth -g pop -p "depeche mode"` lists all stations that have both the words "rock" *and* "pop" in their genre *and* is currently playing "depeche mode".
-
-If you are searching for multi-word phrases, they can be enclosed in quotes. Searching for `"depeche mode"` requires the full string, including the single space, to be present. `depeche mode` requires depeche *and* mode to appear, the order does however not matter.
+The stations publish this information and they usually match pretty well. You can search for several criteria at once. All criteria must match for a station to be listed. For example searching `shoutcast-search -g synth -g pop -p "depeche mode"` lists all stations that have both the words "rock" *and* "pop" in their genre *and* is currently playing "depeche mode".
 
-Criteria are case-insensive, `"Depeche MODE"` and `"depeche mode"` are equal.
+If you are searching for multi-word phrases, they can be enclosed in quotes. Searching for `"depeche mode"` requires the full string, including the single space, to be present. `depeche mode` requires depeche *and* mode to appear, the order does however not matter. Criteria are case-insensive, `"Depeche MODE"` and `"depeche mode"` give the same results.
 
-You can also search for words or phrases without specifying which element to search. `shoutcast-search metallica` searches for stations with the word `metallica` in their genre, current song *or* station name. Any phrase that is not superceeded with an option, e.g. `-p`, will be used as a free text search. `shoutcast-search -g rock metallica` finds all stations with rock as their genre and metallica in any of genre, current song or station name. Use verbose mode to get your search right if you need to..
+You can also search for words or phrases without specifying which element to search. `shoutcast-search metallica` searches for stations with the word `metallica` in their genre, current song *or* station name. Any phrase that is not specified with an option, e.g. `-p`, will be used as a free text search. `shoutcast-search -g rock metallica` finds all stations with rock as their genre and metallica in any of genre, current song or station name. Use verbose mode to get your search right if you need to..
 
 If you don't provide any criteria, shoutcast-search returns the current Top 500 stations.
 
-*Note: due to caching at shoutcast.com, the currently played song per station is somewhat delayd an not always correct.*
+*Note: due to caching at shoutcast.com, the currently played song per station is a bit delayed an not always correct.*
 
 ## Filters
 soutcast-search can filter stations based on quality, number of listeners and codec required.
@@ -109,7 +111,7 @@ The available sorting parameters are:
 ## Options
 By default, shoutcast-search returns the found stations ordered by number of listeners. You can tell shoutcast-search to randomize the order by providing the `-r` option. This option is not applicable if `--sort` is specified.
 
-You can tell shoutcast-search how many results you want by using the `-n` option. `-n 5` returns maximum five stations. Often, it is good to specify `-n 1` when piping the output to an audio player.
+You can tell also set a maximum number of stations to be listed by using the `-n` option. `-n 5` returns maximum five stations. Often, it is good to specify `-n 1` when piping the output to an audio player.
 
 ## Order of evaluation
 shoutcast-search first matches the stations against the criteria; all criteria must match. Next, the results are filtered, again all parameters must match for a station to be listed. The remaining stations are sorted, or randomized based on options, and finally the number of results are limited, if applicable.
@@ -129,17 +131,17 @@ shoutcast-search first matches the stations against the criteria; all criteria m
 	$ shoutcast-search -g rock --sort=ln5b
 
 ## Automation
-I've defined a function in my .bashrc to easily start a radio station using [mpg123](http://en.wikipedia.org/wiki/Mpg123):
+I've have a function in my .bashrc to quickly search and start a station with [mpg123](http://en.wikipedia.org/wiki/Mpg123):
 
 	radio() {
 		killall mpg123; shoutcast-search -n 1 -t mpeg -b ">63" --sort=ln10r $* | xargs mpg123 -q -@ &
 	}
 
-This function selects one random station out of the top ten most listened to playing mpeg at 64+ kbps. I can also specify new options, or change the ones set in the script, from the command line like below.
+This function selects one random station out of the top ten most listened to playing mpeg at 64+ kbps. It also takes arguments to set new options, or change the ones set in the script, from the command line like below.
 
 	$ radio chill
 
-A similar script can easily be put in a shell script and connected to a media button on the keyboard.
+Something similar can easily be put in a shell script and connected to a media button on the keyboard.
 
 ## Media players
 Check your audio players documentation on how to play shoutcast streams. Here follow a few examples.
@@ -157,6 +159,6 @@ Check your audio players documentation on how to play shoutcast streams. Here fo
 	$ killall mpg123; shoutcast-search -t mpeg [...] | xargs mpg123 -q -@ &
 
 ## More information
-For a complete reference, see man-page (`man shoutcast-search`).
+For a complete reference, see the [man-page](http://www.k2h.se/code/shoutcast-search.man.txt) (`man shoutcast-search`).
 
-Written by Henrik Hallberg (<halhen@k2h.se>). Please send me an e-mail if you find bugs, have ideas for new features or just to let me know you use the application. I'd be happy to hear from you.
+Written by Henrik Hallberg (<halhen@k2h.se>). Please send me an e-mail if you find bugs, have ideas for new features or just to let me know you use the application. I'd be happy to hear from you.

pkg/www/_footer.html

@@ -0,0 +1,3 @@
+</div>
+</body>
+</html>

pkg/www/_header.html

@@ -0,0 +1,7 @@
+<html>
+<head>
+<title>PAGETITLE</title>
+<link href="styles.css" rel="stylesheet" type="text/css" />
+</head>
+<body>
+<div id="content">

pkg/www/build_pkg.sh

@@ -10,5 +10,11 @@ RELEASENAME=$APPNAME-$1
 
 echo "Generating www for $APPNAME"
 
-cat $RELEASENAME/shoutcast-search.1 | nroff -man | man2html -title "$RELEASENAME" > releases/www/${RELEASENAME}.man.html
-cp releases/${RELEASENAME}.tar.gz releases/www/
+cat $RELEASENAME/shoutcast-search.1 | nroff -man > releases/www/${RELEASENAME}.man.txt
+cp releases/www/${RELEASENAME}.man.txt releases/www/${APPNAME}.man.txt
+mkdir -p releases/www/dl/
+cp releases/${RELEASENAME}.tar.gz releases/www/dl/
+cp releases/${RELEASENAME}.tar.gz releases/www/dl/${APPNAME}-latest.tar.gz
+
+(cat pkg/www/_header.html | sed s/PAGETITLE/shoutcast-search/; smu -n documentation.md; cat pkg/www/_footer.html) > releases/www/shoutcast-search.html
+cp pkg/www/styles.css releases/www/

pkg/www/styles.css

@@ -0,0 +1,47 @@
+html { 
+
+}
+
+body {
+  background-color: #eee;
+  color:#444;  
+  font-family: Verdana, Arial, SunSans-Regular, Sans-Serif;
+  font-size: 12px;
+  padding:1em 1.5em;
+  margin:0;
+}
+
+#content {
+  float: left;
+  max-width: 50em;
+  margin:0px 0px 50px 0px;
+  overflow: auto;
+} 
+#menu {
+  float: left;
+  width: 25%;
+  overflow: auto;
+}
+
+pre {
+ white-space: pre-wrap; /* css-3 */
+ white-space: -moz-pre-wrap !important; /* Mozilla, since 1999 */
+ white-space: -pre-wrap; /* Opera 4-6 */
+ white-space: -o-pre-wrap; /* Opera 7 */
+ word-wrap: break-word; /* Internet Explorer 5.5+ */
+
+background: #222;
+font-size: 12px;
+background: #222;
+color: #afc81c;
+padding: 0;
+margin: 0;
+border: 1px solid #ccc;
+
+}
+pre code {
+margin: 0 0 0 2.5em;  /*--Left Margin--*/
+padding: 1em 0;
+display: block;
+}
+