[TableGen] Clarify text and fix errors in the Programmer's Reference

[Paul-C-Anagnostopoulos]

Summary

This patch is to the TableGen Programmer's Reference. It adds a note about 'true' and 'false', clarifies some bang operators, and corrects other bang operators.

I will auto-LGTM this patch in 24 hours.

llvm/docs/TableGen/ProgRef.rst

 simple value is the concatenation of the strings. Code fragments become
 strings and then are indistinguishable from them.
 
 .. productionlist::
    SimpleValue2: "true" | "false"
 
 The ``true`` and ``false`` literals are essentially syntactic sugar for the
 integer values 1 and 0. They improve the readability of TableGen files when
-boolean values are used in field values, bit sequences, ``if`` statements.
-etc. When parsed, these literals are converted to integers.
+boolean values are used in field initializations, bit sequences, ``if``
+statements.  etc. When parsed, these literals are converted to integers.
+
+.. note::
+
+  Although ``true`` and ``false`` are literal names for 1 and 0, we
+  recommend as a stylistic rule that you use them for boolean
+  values only.
 
 .. productionlist::
    SimpleValue3: "?"
 
 A question mark represents an uninitialized value.
 
 .. productionlist::
    SimpleValue4: "{" [`ValueList`] "}"

 .. code-block:: text
 
   class isValidSize<int size> {
     bit ret = !cond(!eq(size,  1): 1,
                     !eq(size,  2): 1,
                     !eq(size,  4): 1,
                     !eq(size,  8): 1,
                     !eq(size, 16): 1,
-                    1: 0);
+                    true: 0);
   }
 
   def Data1 {
     int Size = ...;
     bit ValidSize = isValidSize<Size>.ret;
   }
 
 Preprocessing Facilities

 
 ``!cond(``\ *cond1* ``:`` *val1*\ ``,`` *cond2* ``:`` *val2*\ ``, ...,`` *condn* ``:`` *valn*\ ``)``
     This operator tests *cond1* and returns *val1* if the result is true.
     If false, the operator tests *cond2* and returns *val2* if the result is
     true. And so forth. An error is reported if no conditions are true.
 
     This example produces the sign word for an integer::
 
-    !cond(!lt(x, 0) : "negative", !eq(x, 0) : "zero", 1 : "positive")
+    !cond(!lt(x, 0) : "negative", !eq(x, 0) : "zero", true : "positive")
 
-``!dag(``\ *op*\ ``,`` *children*\ ``,`` *names*\ ``)``
-    This operator creates a DAG node.
-    The *children* and *names* arguments must be lists
+``!dag(``\ *op*\ ``,`` *arguments*\ ``,`` *names*\ ``)``
+    This operator creates a DAG node with the given operator and
+    arguments. The *arguments* and *names* arguments must be lists
     of equal length or uninitialized (``?``). The *names* argument
     must be of type ``list<string>``.
 
-    Due to limitations of the type system, *children* must be a list of items
+    Due to limitations of the type system, *arguments* must be a list of items
     of a common type. In practice, this means that they should either have the
     same type or be records with a common superclass. Mixing ``dag`` and
     non-``dag`` items is not possible. However, ``?`` can be used.
 
     Example: ``!dag(op, [a1, a2, ?], ["name1", "name2", "name3"])`` results in
-    ``(op a1:$name1, a2:$name2, ?:$name3)``.
+    ``(op a1-value:$name1, a2-value:$name2, ?:$name3)``.
 
 ``!empty(``\ *a*\ ``)``
     This operator produces 1 if the string, list, or DAG *a* is empty; 0 otherwise.
     A dag is empty if it has no arguments; the operator does not count.
 
 ``!eq(`` *a*\ `,` *b*\ ``)``
     This operator produces 1 if *a* is equal to *b*; 0 otherwise.
-    The arguments must be ``bit``, ``int``, or ``string`` values.
+    The arguments must be ``bit``, ``bits``, ``int``, or ``string`` values.
     Use ``!cast<string>`` to compare other types of objects.
 
-``!foldl(``\ *start*\ ``,`` *list*\ ``,`` *a*\ ``,`` *b*\ ``,`` *expr*\ ``)``
+``!foldl(``\ *init*\ ``,`` *list*\ ``,`` *acc*\ ``,`` *var*\ ``,`` *expr*\ ``)``
     This operator performs a left-fold over the items in *list*. The
-    variable *a* acts as the accumulator and is initialized to *start*.
-    The variable *b* is bound to each element in the *list*. The *expr*
-    expression is evaluated for each element and presumably uses *a* and *b*
-    to calculate the accumulated value, which ``!foldl`` stores in *a*. The
-    type of *a* is the same as *start*; the type of *b* is the same as the
-    elements of *list*; *expr* must have the same type as *start*.
+    variable *acc* acts as the accumulator and is initialized to *init*.
+    The variable *var* is bound to each element in the *list*. The
+    expression is evaluated for each element and presumably uses *acc* and
+    *var* to calculate the accumulated value, which ``!foldl`` stores back in
+    *acc*. The type of *acc* is the same as *init*; the type of *var* is the
+    same as the elements of *list*; *expr* must have the same type as *init*.
 
     The following example computes the total of the ``Number`` field in the
     list of records in ``RecList``::
 
       int x = !foldl(0, RecList, total, rec, !add(total, rec.Number));
 
-``!foreach(``\ *var*\ ``,`` *seq*\ ``,`` *form*\ ``)``
+``!foreach(``\ *var*\ ``,`` *sequence*\ ``,`` *expr*\ ``)``
     This operator creates a new ``list``/``dag`` in which each element is a
-    function of the corresponding element in the *seq* ``list``/``dag``. To
-    perform the function, TableGen binds the variable *var* to an element and
-    then evaluates the *form* expression. The form presumably refers to the
-    variable *var* and calculates the result value.
+    function of the corresponding element in the *sequence* ``list``/``dag``.
+    To perform the function, TableGen binds the variable *var* to an element
+    and then evaluates the expression. The expression presumably refers
+    to the variable *var* and calculates the result value.
+
+    If you simply want to create a list of a certain length containing
+    the same value repeated multiple times, see ``!listsplat``.
 
 ``!ge(``\ *a*\ `,` *b*\ ``)``
     This operator produces 1 if *a* is greater than or equal to *b*; 0 otherwise.
-    The arguments must be ``bit``, ``int``, or ``string`` values.
-    Use ``!cast<string>`` to compare other types of objects.
+    The arguments must be ``bit``, ``bits``, or ``int`` values.
 
 ``!getdagop(``\ *dag*\ ``)`` --or-- ``!getdagop<``\ *type*\ ``>(``\ *dag*\ ``)``
     This operator produces the operator of the given *dag* node.
     Example: ``!getdagop((foo 1, 2))`` results in ``foo``. Recall that
     DAG operators are always records.
 
     The result of ``!getdagop`` can be used directly in a context where
     any record class at all is acceptable (typically placing it into
``!getdagop(``\ *dag*\ ``)`` --or-- ``!getdagop<``\ *type*\ ``>(``\ *dag*\ ``)``
 
     But to create a new DAG node that reuses the operator from another, no
     cast is necessary::
 
       dag d = !dag(!getdagop(someDag), args, names);
 
 ``!gt(``\ *a*\ `,` *b*\ ``)``
     This operator produces 1 if *a* is greater than *b*; 0 otherwise.
-    The arguments must be ``bit``, ``int``, or ``string`` values.
-    Use ``!cast<string>`` to compare other types of objects.
+    The arguments must be ``bit``, ``bits``, or ``int`` values.
 
 ``!head(``\ *a*\ ``)``
     This operator produces the zeroth element of the list *a*.
     (See also ``!tail``.)
 
 ``!if(``\ *test*\ ``,`` *then*\ ``,`` *else*\ ``)``
   This operator evaluates the *test*, which must produce a ``bit`` or
   ``int``. If the result is not 0, the *then* expression is produced; otherwise
   the *else* expression is produced.
 
 ``!interleave(``\ *list*\ ``,`` *delim*\ ``)``
     This operator concatenates the items in the *list*, interleaving the
     *delim* string between each pair, and produces the resulting string.
     The list can be a list of string, int, bits, or bit. An empty list
     results in an empty string. The delimiter can be the empty string.
 
 ``!isa<``\ *type*\ ``>(``\ *a*\ ``)``
     This operator produces 1 if the type of *a* is a subtype of the given *type*; 0
     otherwise.
 
 ``!le(``\ *a*\ ``,`` *b*\ ``)``
     This operator produces 1 if *a* is less than or equal to *b*; 0 otherwise.
-    The arguments must be ``bit``, ``int``, or ``string`` values.
-    Use ``!cast<string>`` to compare other types of objects.
+    The arguments must be ``bit``, ``bits``, or ``int`` values.
 
 ``!listconcat(``\ *list1*\ ``,`` *list2*\ ``, ...)``
     This operator concatenates the list arguments *list1*, *list2*, etc., and
     produces the resulting list. The lists must have the same element type.
 
 ``!listsplat(``\ *value*\ ``,`` *count*\ ``)``
     This operator produces a list of length *count* whose elements are all
     equal to the *value*. For example, ``!listsplat(42, 3)`` results in
     ``[42, 42, 42]``.
 
 ``!lt(``\ *a*\ `,` *b*\ ``)``
     This operator produces 1 if *a* is less than *b*; 0 otherwise.
-    The arguments must be ``bit``, ``int``, or ``string`` values.
-    Use ``!cast<string>`` to compare other types of objects.
+    The arguments must be ``bit``, ``bits``, or ``int`` values.
 
 ``!mul(``\ *a*\ ``,`` *b*\ ``, ...)``
     This operator multiplies *a*, *b*, etc., and produces the product.
 
 ``!ne(``\ *a*\ `,` *b*\ ``)``
     This operator produces 1 if *a* is not equal to *b*; 0 otherwise.
-    The arguments must be ``bit``, ``int``, or ``string`` values.
+    The arguments must be ``bit``, ``bits``, ``int``, or ``string`` values.
     Use ``!cast<string>`` to compare other types of objects.
 
 ``!not(``\ *a*\ ``)``
     This operator performs a logical NOT on *a*, which must be
     an integer. The argument 0 results in 1 (true); any other
     argument results in 0 (false).
 
 ``!or(``\ *a*\ ``,`` *b*\ ``, ...)``