Docs: Advanced tag use

Add complex pycode example, generating tasks and then parsing tags to select source files.  Warn against doing it, and reiterate the usefulness of `--dumptasks` and `--dumpcfg`.
Modify gen.sh for modifiable script/task and to echo how it was called (in case they need to be regenerated, which isn't a problem for the regular example/task1 but is for the complex one).

docs/examples/tags/complex.log

@@ -0,0 +1,47 @@
+./gen.sh -s complex -t unbounded_hAdX
+$ sby --dumptasks complex.sby
+unbounded_hAdX
+unbounded_hAdY
+unbounded_hBdX
+unbounded_hBdY
+liveness_hAdX
+liveness_hAdY
+liveness_hBdX
+liveness_hBdY
+$ sby --dumptags complex.sby
+deviceX
+deviceY
+hostA
+hostB
+liveness
+liveness_hAdX
+liveness_hAdY
+liveness_hBdX
+liveness_hBdY
+unbounded
+unbounded_hAdX
+unbounded_hAdY
+unbounded_hBdX
+unbounded_hBdY
+$ sby --dumptags complex.sby unbounded_hAdX
+deviceX
+hostA
+unbounded
+unbounded_hAdX
+$ sby --dumpcfg complex.sby unbounded_hAdX
+[options]
+mode prove
+
+[engines]
+abc pdr
+
+[script]
+read -sv hostA.v
+read -sv deviceX.v
+read -sv unbounded.v
+prep -top unbounded
+
+[files]
+hostA.v
+deviceX.v
+unbounded.v

docs/examples/tags/complex.sby

@@ -0,0 +1,35 @@
+[tasks]
+--pycode-begin--
+for m in ['unbounded', 'liveness']:
+    for h in ['A', 'B']:
+        for d in ['X', 'Y']:
+            output(f'{m}_h{h}d{d} {m} host{h} device{d}')
+--pycode-end--
+
+[options]
+unbounded: mode prove
+liveness: mode live
+
+[engines]
+unbounded: abc pdr
+liveness: aiger suprove
+
+[script]
+--pycode-begin--
+sources = []
+for tag in tags:
+    if tag.startswith(('host', 'device')):
+        sources.append(tag)
+        output(f'read -sv {tag}.v')
+
+if task is not None:
+    top = task.split('_')[0]
+    sources.append(top)
+    output(f'read -sv {top}.v')
+    output(f'prep -top {top}')
+
+output('')
+output('[files]')
+for source in sources:
+    output(f'{source}.v')
+--pycode-end--

docs/examples/tags/example.log

@@ -1,3 +1,4 @@
+./gen.sh 
 $ sby --dumptasks example.sby
 task1
 task2

docs/examples/tags/gen.sh

@@ -2,27 +2,35 @@
 set -eu
 
 sby="sby"
-script="example.sby"
+script="example"
 task="task1"
 
-while getopts :s: opt; do
+while getopts :S:s:t: opt; do
     case "$opt" in
-        s)
+        S)
             sby=$OPTARG
             ;;
+        s)
+            script=$OPTARG
+            ;;
+        t)
+            task=$OPTARG
+            ;;
         *)
-            echo "Usage: $0 [-s SBY command]\n" >&2
+            echo "Usage: $0 [-s SBY command] [-s .sby file] [-t task]\n" >&2
             exit 1
             ;;
     esac
 done
 
+
 # log our commands and output
+echo "$0 $@" > ${script}.log
 PS4="$ "
-exec > >(tee example.log) 2>&1
+exec > >(tee -a ${script}.log) 2>&1
 set -x
 
-$sby --dumptasks $script
-$sby --dumptags $script
-$sby --dumptags $script $task
-$sby --dumpcfg $script $task
+$sby --dumptasks ${script}.sby
+$sby --dumptags ${script}.sby
+$sby --dumptags ${script}.sby $task
+$sby --dumpcfg ${script}.sby $task