--- doc/docbase/instrument_scripts/nksp/reference/functions/nksp_event_status_function.html	2016/07/10 14:44:04	2936
+++ doc/docbase/instrument_scripts/nksp/reference/functions/nksp_event_status_function.html	2017/05/20 13:37:20	3194
@@ -57,26 +57,55 @@
       The following example shows a simple stuttering effect. The script
       runs in an endless loop and turns down and up the volume all 200ms.
       To stop the endless loop once the respective note died, the return
-      value of <code>event_status()</code> is compared bitwise with built-in constant bit flag
-      <code>$EVENT_STATUS_NOTE_QUEUE</code>.
+      value of <code>event_status()</code> is compared with built-in constant
+      bit flag <code>$EVENT_STATUS_INACTIVE</code>.
+    </p>
+    <code>
+on note
+  while (1)
+    wait(200000)
+    if (event_status($EVENT_ID) = $EVENT_STATUS_INACTIVE)
+      exit() { note is no longer alive, so stop script here }
+    end if
+    change_vol($EVENT_ID, -20000)  { Reduce volume by 20 dB. }
+
+    wait(200000)
+    if (event_status($EVENT_ID) = $EVENT_STATUS_INACTIVE)
+      exit() { note is no longer alive, so stop script here }
+    end if
+    change_vol($EVENT_ID, 0)  { Increase volume to 0 dB. }
+  end while
+end on
+    </code>
+    <p>
+      Note: since the built-in constants returned by this function are actually bit flags,
+      and since further bit flags might be added in future for this function, the actual
+      long-term safe and correct way to check the return value of <code>event_status()</code>
+      is a bitwise comparison. So the recommended "correct" way for the example above would
+      actually be:
     </p>
     <code>
 on note
   while (1)
     wait(200000)
     if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
-      exit()
+      exit() { note is no longer alive, so stop script here }
     end if
     change_vol($EVENT_ID, -20000)  { Reduce volume by 20 dB. }
 
     wait(200000)
     if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
-      exit()
+      exit() { note is no longer alive, so stop script here }
     end if
     change_vol($EVENT_ID, 0)  { Increase volume to 0 dB. }
   end while
 end on
     </code>
+    <p>
+      In practice however, the first version of this example is much easier to
+      read (and write) though, and new bit flags will probably not be added to
+      this function in near future. But that's up to you to decide!
+    </p>
 
     <h3>Availabilty</h3>
     <p>Since LinuxSampler 2.0.0.svn12.<p>