Index: openacs-4/packages/acs-tcl/tcl/utilities-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-tcl/tcl/utilities-procs.tcl,v
diff -u -r1.189.2.5 -r1.189.2.6
--- openacs-4/packages/acs-tcl/tcl/utilities-procs.tcl	10 Mar 2019 21:34:33 -0000	1.189.2.5
+++ openacs-4/packages/acs-tcl/tcl/utilities-procs.tcl	13 Mar 2019 11:51:59 -0000	1.189.2.6
@@ -1322,7 +1322,20 @@
     pairs where first element in the pair is convert from value and second
     element is convert to value. The last value is default value, which will
     be returned in the case convert from values matches the given value to
-    be decoded.
+    be decoded.<br>
+    <br>
+    Note that in most cases native tcl idioms such as expr or switch
+    will do the trick. This proc CAN make sense when one has many
+    alternatives to decode, as in such cases a switch statement would
+    not be as compact.<br>
+    <br>
+    Good usage:<br>
+    <code>ad_decode $value f Foo b Bar d Dan s Stan l Lemon m Melon
+    Unknown</code> ---> a oneliner as opposed to a long switch
+    statement<br>
+    <br>
+    Bad usage:<br>
+    <code>ad_decode $boolean_p t 0 1</code> ---> just use <code>expr {!$boolean_p}</code>
 } {
     set num_args [llength $args]
     set input_value [lindex $args 0]