Merge pull request #660 from Alphakilo/development

Clarification of "#!/"-stuff — many thanks for cleaning all this up!

README.md

@@ -323,9 +323,9 @@ The `pa` group is used to specify settings relevant to the PulseAudio backend. Y
 
 Shairport Sync can run programs just before it starts to play an audio stream and just after it finishes. You specify them using the `sessioncontrol` group settings `run_this_before_play_begins` and `run_this_after_play_ends`. This is to facilitate situations where something has to be done before and after playing, e.g. switching on an amplifier beforehand and switching it off afterwards. Set the `wait_for_completion` value to `"yes"` for Shairport Sync to wait until the respective commands have been completed before continuing.
 
-Note that the full path to the programs must be specified, and script files will not be executed unless they are marked as executable and have the standard `#!/bin/...` first line. (This behaviour may be different from other Shairports.)
+Note that the full path to the programs must be specified, and script files will not be executed unless they are marked as executable and have the appropriate shebang `#!/bin/...` as the first line. (This behaviour may be different from other Shairports.)
 
-Shairport Sync can run a program whenever the volume is set or changed. You specify them using the `general` group settings `run_this_when_volume_changes`. This is to facilitate situations where something has to be done when the volume changes, e.g. adjust an external mixer value. Set the `wait_for_completion` value to `"yes"` for Shairport Sync to wait until the command has been completed before continuing. Again, please note that the full path to the program must be specified, and script files will not be executed unless they are marked as executable and have the standard `#!/bin/...` first line.
+Shairport Sync can run a program whenever the volume is set or changed. You specify them using the `general` group settings `run_this_when_volume_changes`. This is to facilitate situations where something has to be done when the volume changes, e.g. adjust an external mixer value. Set the `wait_for_completion` value to `"yes"` for Shairport Sync to wait until the command has been completed before continuing. Again, please note that the full path to the program must be specified, and script files will not be executed unless they are marked as executable and have the appropriate shebang `#!/bin/...` as the first line.
 
 Note: Shairport Sync can take configuration settings from command line options. This is mainly for backward compatibility, but sometimes still useful. For normal use, it is strongly recommended that you use the configuration file method.
 

man/shairport-sync.7

@@ -151,7 +151,7 @@ The purpose of this silent lead-in is to give the backend sufficient time to pre
 If the value chosen is too short for synchronised backends such as the ALSA, sndio or PA backends, then audio will not be synchronised correctly at the start of play. The default is to have a silent lead-in of approximately the same time as the latency set by the client.
 .TP
 \fBrun_this_when_volume_is_set=\f1\fI"/full/path/to/application/and/args"\f1\fB;\f1
-Here you can specify a program and its arguments that will be run when the volume is set or changed. Be careful to include the full path to the application. The application must be marked as executable and, if it is a script, its first line must begin with the standard \fI#!/bin/...\f1 as appropriate.
+Here you can specify a program and its arguments that will be run when the volume is set or changed. Be careful to include the full path to the application. The application must be marked as executable and, if it is a script, its first line must begin with the appropriate shebang \fI#!/bin/...\f1.
 
 The desired AirPlay volume is appended to the end of the command line - leave a space if you want it treated as an extra argument. AirPlay volume goes from 0.0 to -30.0 and -144.0 means "mute".
 .TP
@@ -267,10 +267,10 @@ The maximum packet size for any UDP metadata. This must be between 500 or 65000.
 shairport-sync can run programs just before it starts to play an audio stream and just after it finishes. You specify them using the sessioncontrol group settings run_this_before_play_begins and run_this_after_play_ends.
 .TP
 \fBrun_this_before_play_begins=\f1\fI"/path/to/application and args"\f1\fB;\f1
-Here you can specify a program and its arguments that will be run just before a play session begins. Be careful to include the full path to the application. The application must be marked as executable and, if it is a script, its first line must begin with the standard \fI#!/bin/...\f1 as appropriate.
+Here you can specify a program and its arguments that will be run just before a play session begins. Be careful to include the full path to the application. The application must be marked as executable and, if it is a script, its first line must begin with the appropriate shebang \fI#!/bin/...\f1.
 .TP
 \fBrun_this_after_play_ends=\f1\fI"/path/to/application and args"\f1\fB;\f1
-Here you can specify a program and its arguments that will be run just after a play session ends. Be careful to include the full path to the application. The application must be marked as executable and, if it is a script, its first line must begin with the standard \fI#!/bin/...\f1 as appropriate.
+Here you can specify a program and its arguments that will be run just after a play session ends. Be careful to include the full path to the application. The application must be marked as executable and, if it is a script, its first line must begin with the appropriate shebang \fI#!/bin/...\f1.
 .TP
 \fBwait_for_completion=\f1\fI"choice"\f1\fB;\f1
 Set \fIchoice\f1 to "yes" to make shairport-sync wait until the programs specified in the \fBrun_this_before_play_begins\f1, \fBrun_this_after_play_ends\f1 and \fBrun_this_when_volume_is_set\f1 have completed execution before continuing. The default is "no".
@@ -299,7 +299,7 @@ The following substitutions are allowed: \fB%h\f1 for the computer's hostname, \
 The default is "%H", which is replaced by the hostname with the first letter capitalised.
 .TP
 \fB-B \f1\fIprogram\f1\fB | --on-start=\f1\fIprogram\f1
-Execute \fIprogram\f1 when playback is about to begin. Specify the full path to the program, e.g. \fI/usr/bin/logger\f1. Executable scripts can be used, but they must have \fI#!/bin/sh\f1 (or whatever is appropriate) in the headline.
+Execute \fIprogram\f1 when playback is about to begin. Specify the full path to the program, e.g. \fI/usr/bin/logger\f1. Executable scripts can be used, but they must have the appropriate shebang (\fI#!/bin/sh\f1) in the headline.
 
 If you want shairport-sync to wait until the command has completed before starting to play, select the \fB-w\f1 option as well. 
 .TP
@@ -315,7 +315,7 @@ Please note that this feature is deprecated and will be removed in a future vers
 Instruct shairport-sync to demonise itself. It will write its Process ID (PID) to a file, usually at \fI/var/run/shairport-sync/shairport-sync.pid\f1, which is used by the \fB-k\f1, \fB-D\f1 and \fB-R\f1 options to locate the daemon at a later time. See also the \fB-j\f1 option. 
 .TP
 \fB-E \f1\fIprogram\f1\fB | --on-stop=\f1\fIprogram\f1
-Execute \fIprogram\f1 when playback has ended. Specify the full path to the program, e.g. \fI/usr/bin/logger\f1. Executable scripts can be used, but they must have \fI#!/bin/sh\f1 (or whatever is appropriate) in the headline.
+Execute \fIprogram\f1 when playback has ended. Specify the full path to the program, e.g. \fI/usr/bin/logger\f1. Executable scripts can be used, but they must have the appropriate shebang (\fI#!/bin/sh\f1) in the headline.
 
 If you want shairport-sync to wait until the command has completed before continuing, select the \fB-w\f1 option as well. 
 .TP

man/shairport-sync.7.xml

@@ -275,7 +275,7 @@
     <option>
     <p><opt>run_this_when_volume_is_set=</opt><arg>"/full/path/to/application/and/args"</arg><opt>;</opt></p>
     <optdesc><p>Here you can specify a program and its arguments that will be run when the volume is set or changed. Be careful to include the full path to the application.
-    The application must be marked as executable and, if it is a script, its first line must begin with the standard <file>#!/bin/...</file> as appropriate.</p>
+    The application must be marked as executable and, if it is a script, its first line must begin with the standard shebang <file>#!/bin/...</file> as appropriate.</p>
     <p>The desired AirPlay volume is appended to the end of the command line - leave a space if you want it treated as an extra argument.
     AirPlay volume goes from 0.0 to -30.0 and -144.0 means "mute".</p></optdesc>
     </option>
@@ -446,12 +446,12 @@
     <option>
     <p><opt>run_this_before_play_begins=</opt><arg>"/path/to/application and args"</arg><opt>;</opt></p>
     <optdesc><p>Here you can specify a program and its arguments that will be run just before a play session begins. Be careful to include the full path to the application.
-    The application must be marked as executable and, if it is a script, its first line must begin with the standard <file>#!/bin/...</file> as appropriate.</p></optdesc>
+    The application must be marked as executable and, if it is a script, its first line must begin with the standard shebang <file>#!/bin/...</file> as appropriate.</p></optdesc>
     </option>
     <option>
     <p><opt>run_this_after_play_ends=</opt><arg>"/path/to/application and args"</arg><opt>;</opt></p>
     <optdesc><p>Here you can specify a program and its arguments that will be run just after a play session ends. Be careful to include the full path to the application.
-    The application must be marked as executable and, if it is a script, its first line must begin with the standard <file>#!/bin/...</file> as appropriate.</p></optdesc>
+    The application must be marked as executable and, if it is a script, its first line must begin with the standard shebang <file>#!/bin/...</file> as appropriate.</p></optdesc>
     </option>
     <option>
     <p><opt>wait_for_completion=</opt><arg>"choice"</arg><opt>;</opt></p>
@@ -511,8 +511,8 @@
 		<optdesc><p>
 		Execute <arg>program</arg> when playback is about to begin. Specify the 
 		full path to the program, e.g. <file>/usr/bin/logger</file>.
-		Executable scripts can be used, but they must have <file>#!/bin/sh</file> (or
-		whatever is appropriate) in the headline.</p>
+		Executable scripts can be used, but they must have the appropriate shebang
+    (<file>#!/bin/sh</file> in the headline.</p>
 		
 		<p>If you want shairport-sync to wait until the command has
 		completed before starting to play, select the <opt>-w</opt> option as well.
@@ -554,8 +554,8 @@
 		<optdesc><p>
 		Execute <arg>program</arg> when playback has ended. Specify the 
 		full path to the program, e.g. <file>/usr/bin/logger</file>.
-		Executable scripts can be used, but they must have <file>#!/bin/sh</file> (or
-		whatever is appropriate) in the headline.</p>		
+		Executable scripts can be used, but they must have the appropriate shebang
+    (<file>#!/bin/sh</file> in the headline.</p>
 		<p>If you want shairport-sync to wait until the command has
 		completed before continuing, select the <opt>-w</opt> option as well.
 		</p></optdesc>

man/shairport-sync.html

@@ -256,7 +256,7 @@
     
     <p><b>run_this_when_volume_is_set=</b><em>&quot;/full/path/to/application/and/args&quot;</em><b>;</b></p>
     <p>Here you can specify a program and its arguments that will be run when the volume is set or changed. Be careful to include the full path to the application.
-    The application must be marked as executable and, if it is a script, its first line must begin with the standard <em>#!/bin/...</em> as appropriate.</p>
+    The application must be marked as executable and, if it is a script, its first line must begin with the appropriate shebang <em>#!/bin/...</em>.</p>
     <p>The desired AirPlay volume is appended to the end of the command line - leave a space if you want it treated as an extra argument.
     AirPlay volume goes from 0.0 to -30.0 and -144.0 means &quot;mute&quot;.</p>
     
@@ -427,12 +427,12 @@
     
     <p><b>run_this_before_play_begins=</b><em>&quot;/path/to/application and args&quot;</em><b>;</b></p>
     <p>Here you can specify a program and its arguments that will be run just before a play session begins. Be careful to include the full path to the application.
-    The application must be marked as executable and, if it is a script, its first line must begin with the standard <em>#!/bin/...</em> as appropriate.</p>
+    The application must be marked as executable and, if it is a script, its first line must begin with the appropriate shebang <em>#!/bin/...</em>.</p>
     
     
     <p><b>run_this_after_play_ends=</b><em>&quot;/path/to/application and args&quot;</em><b>;</b></p>
     <p>Here you can specify a program and its arguments that will be run just after a play session ends. Be careful to include the full path to the application.
-    The application must be marked as executable and, if it is a script, its first line must begin with the standard <em>#!/bin/...</em> as appropriate.</p>
+    The application must be marked as executable and, if it is a script, its first line must begin with the appropriate shebang <em>#!/bin/...</em>.</p>
     
     
     <p><b>wait_for_completion=</b><em>&quot;choice&quot;</em><b>;</b></p>
@@ -496,8 +496,8 @@
 		<p>
 		Execute <em>program</em> when playback is about to begin. Specify the 
 		full path to the program, e.g. <em>/usr/bin/logger</em>.
-		Executable scripts can be used, but they must have <em>#!/bin/sh</em> (or
-		whatever is appropriate) in the headline.</p>
+    Executable scripts can be used, but they must have the appropriate shebang
+    <em>#!/bin/sh</em> in the headline.</p>
 		
 		<p>If you want shairport-sync to wait until the command has
 		completed before starting to play, select the <b>-w</b> option as well.
@@ -539,8 +539,8 @@
 		<p>
 		Execute <em>program</em> when playback has ended. Specify the 
 		full path to the program, e.g. <em>/usr/bin/logger</em>.
-		Executable scripts can be used, but they must have <em>#!/bin/sh</em> (or
-		whatever is appropriate) in the headline.</p>		
+    Executable scripts can be used, but they must have the appropriate shebang
+    <em>#!/bin/sh</em> in the headline.</p>	
 		<p>If you want shairport-sync to wait until the command has
 		completed before continuing, select the <b>-w</b> option as well.
 		</p>

scripts/shairport-sync.conf

@@ -51,8 +51,8 @@ general =
 // Advanced parameters for controlling how a Shairport Sync runs
 sessioncontrol = 
 {
-//	run_this_before_play_begins = "/full/path/to/application and args"; // make sure the application has executable permission. It it's a script, include the #!... stuff on the first line
-//	run_this_after_play_ends = "/full/path/to/application and args"; // make sure the application has executable permission. It it's a script, include the #!... stuff on the first line
+//	run_this_before_play_begins = "/full/path/to/application and args"; // make sure the application has executable permission. If it's a script, include the shebang (#!/bin/...) on the first line
+//	run_this_after_play_ends = "/full/path/to/application and args"; // make sure the application has executable permission. If it's a script, include the shebang (#!/bin/...) on the first line
 //	wait_for_completion = "no"; // set to "yes" to get Shairport Sync to wait until the "run_this..." applications have terminated before continuing
 //	allow_session_interruption = "no"; // set to "yes" to allow another device to interrupt Shairport Sync while it's playing from an existing audio source
 //	session_timeout = 120; // wait for this number of seconds after a source disappears before terminating the session and becoming available again.

shairport.c

@@ -246,8 +246,8 @@ void usage(char *progname) {
   printf("    -E, --on-stop=PROGRAM   run PROGRAM when playback has ended.\n");
   printf("                            For -B and -E options, specify the full path to the program, "
          "e.g. /usr/bin/logger.\n");
-  printf("                            Executable scripts work, but must have #!/bin/sh (or "
-         "whatever) in the headline.\n");
+  printf("                            Executable scripts work, but must have the appropriate shebang "
+         "(#!/bin/sh) in the headline.\n");
   printf(
       "    -w, --wait-cmd          wait until the -B or -E programs finish before continuing.\n");
   printf("    -o, --output=BACKEND    select audio output method.\n");