If-then-else documentation for forking conditional (fix #942)

docs/content/3.manual/manual.yml

@@ -1863,9 +1863,9 @@ sections:
           need something more like `if (.name | length) > 0 then A else
           B end` instead.
 
-          If the condition A produces multiple results, it is
-          considered "true" if any of those results is not false or
-          null. If it produces zero results, it's considered false.
+          If the condition `A` produces multiple results, then `B` is evaluated
+          once for each result that is not false or null, and `C` is evaluated
+          once for each false or null.
 
           More cases can be added to an if using `elif A then B` syntax.
 

docs/content/3.manual/v1.3/manual.yml

@@ -913,9 +913,9 @@ sections:
           need something more like `if (.name | count) > 0 then A else
           B end` instead.
 
-          If the condition A produces multiple results, it is
-          considered "true" if any of those results is not false or
-          null. If it produces zero results, it's considered false.
+          If the condition `A` produces multiple results, then `B` is evaluated
+          once for each result that is not false or null, and `C` is evaluated
+          once for each false or null.
 
           More cases can be added to an if using `elif A then B` syntax.
 

docs/content/3.manual/v1.4/manual.yml

@@ -1315,9 +1315,9 @@ sections:
           need something more like `if (.name | length) > 0 then A else
           B end` instead.
 
-          If the condition A produces multiple results, it is
-          considered "true" if any of those results is not false or
-          null. If it produces zero results, it's considered false.
+          If the condition `A` produces multiple results, then `B` is evaluated
+          once for each result that is not false or null, and `C` is evaluated
+          once for each false or null.
 
           More cases can be added to an if using `elif A then B` syntax.
 

docs/content/3.manual/v1.5/manual.yml

@@ -1794,9 +1794,9 @@ sections:
           need something more like `if (.name | length) > 0 then A else
           B end` instead.
 
-          If the condition A produces multiple results, it is
-          considered "true" if any of those results is not false or
-          null. If it produces zero results, it's considered false.
+          If the condition `A` produces multiple results, then `B` is evaluated
+          once for each result that is not false or null, and `C` is evaluated
+          once for each false or null.
 
           More cases can be added to an if using `elif A then B` syntax.
 

tests/jq.test

@@ -867,8 +867,21 @@ try (def x: reverse; x=10) catch .
 [{"foo":0},{"foo":1},{"foo":[]},{"foo":true},{"foo":false},{"foo":null},{"foo":"foo"},{}]
 ["yep","yep","yep","yep","nope","nope","yep","nope"]
 
+[if 1,null,2 then 3 else 4 end]
+null
+[3,4,3]
 
-# FIXME: define/test behaviour of 'if (.foo,.bar) then A else B end'
+[if empty then 3 else 4 end]
+null
+[]
+
+[if 1 then 3,4 else 5 end]
+null
+[3,4]
+
+[if null then 3 else 5,6 end]
+null
+[5,6]
 
 [.[] | [.foo[] // .bar]]
 [{"foo":[1,2], "bar": 42}, {"foo":[1], "bar": null}, {"foo":[null,false,3], "bar": 18}, {"foo":[], "bar":42}, {"foo": [null,false,null], "bar": 41}]