From 12c44f0a19a3cfc729370550b3f18d19f3f8633f Mon Sep 17 00:00:00 2001
From: Cesare Tinelli <cesare-tinelli@uiowa.edu>
Date: Fri, 30 Aug 2024 14:29:21 -0500
Subject: [PATCH 01/12] Several edits to  improve readability and conform to
 Markdown guidelines

---
 .DS_Store      |  Bin 0 -> 8196 bytes
 user_manual.md | 1021 ++++++++++++++++++++++++++----------------------
 2 files changed, 562 insertions(+), 459 deletions(-)
 create mode 100644 .DS_Store

diff --git a/.DS_Store b/.DS_Store
new file mode 100644
index 0000000000000000000000000000000000000000..e9378fd5e1f00250b64b7597856e410349f09352
GIT binary patch
literal 8196
zcmeHMJ#Q016r6QzY$=T^6j5!1=#WB<l#Av3f>2U`ohXU0b5>&4Ttx#y)JWt9(9lrv
z15!|>;zQy`P|yGc%-dbtyLUdQAV|EGcIUG1y_?aTb?fH<FumE{Ca?jZ!ztKZ=dxl*
zTxMl7!j2^x)?;+AxjW3qlS-y;r~~SNI-m}y1M0xP;sDQV8J(JQ-$!*-2h@T8(gArt
zSWdw#VByidI=HwNfY{`=8@%qy1<?k~0u~+_;V{0G=u1s#F^n(gz72U<z`~<1hY8Jx
z3Ct#RD8{k#{??_#WFB=@2h@S81D0D&+{6KnFiraRYdf#w*f{U^2cvwzz0TX-*NYq5
z=i6y~@0an(Vf5R;^$V7wJ?F(CW*8*wxbmf%5o>sQ>)orMp>&^dzEo15mFV#=ofd`|
z<31i>Kh<JhP)ihzbzD7K=twe_8dhhl;BS*Z$1$cj;nOJj@$IAYBgu$${3sSWO81HV
zsLx9D__t;o6O8y|<g;;%)6|ofPn@14Bi8f%EYefTT6$BTmFU4|l3^XEd_GfZqC2>Q
zef~Wy=`znB)n~@~?%sYs|NPY4H}>uK*@@o9MD(sv-wB3^Z>`zZG7{_QJ^V1&6Y66A
zYBb?%Tj6Wbja8mBw%(-CnD_D7r#Wv_A9JtHNccO?gkJ`a=Wak7Fbi0C^ar?}|Kf%Y
zb>Q+GSo72y(*N(&|Neh@0+m@EPzV0F1E$&E?e|C%dg}_I^xBs59;Xb+D?GXqF0LIX
hx^|qn_=h2{EmNf?3s`vM4u^gba5m_o4*XRIegZG(532wG

literal 0
HcmV?d00001

diff --git a/user_manual.md b/user_manual.md
index f2eb8798..44d745c2 100644
--- a/user_manual.md
+++ b/user_manual.md
@@ -1,111 +1,141 @@
-# Introduction
+# The Ethos user manual
 
 This is the user manual for the Ethos, an efficient and extensible tool for checking proofs of Satisfiability Modulo Theories (SMT) solvers.
 
-## Building ethos
+## Building the Ethos executable
 
-The source code for ethos is available here: https://github.com/cvc5/ethos.
+The source code for Ethos is available at <https://github.com/cvc5/ethos>.
 To build ethos, run:
-```
+
+```shell
 mkdir build
 cd build
 cmake ..
 ```
+
 The `ethos` binary will be available in `build/src/`.
 
 ### Debug build
 
 By default, the above will be a production build of `ethos`. To build a debug version of `ethos`, that is significantly slower but has assertions and trace messages enabled, run:
-```
+
+```shell
 mkdir build -DCMAKE_BUILD_TYPE=Debug
 cd build
 cmake ..
 ```
+
 The `ethos` binary will be available in `build/src/`.
 
-## Command line interface of ethos
+## Command line interface
 
-`ethos` can be run from the command line via:
-```
+Ethos can be run from the command line via:
+
+```shell
 ethos <option>* <file>
 ```
+
 The set of available options `<option>` are given in the appendix. Note the command line interface of `ethos` expects exactly one file (which itself may reference other files via the `include` command as we will see later). The file and options can appear in any order.
 
 The Ethos will either emit an error message indicating:
-- The kind of failure (type checking, proof checking, lexer error),
-- The line and column of the failure.
-Otherwise, the Ethos will print a [successful response](#responses) when it finished parsing all commands in the file or encounters and `exit` command.
+
+- the kind of failure (type checking, proof checking, lexer error),
+- the line and column of the failure,
+
+or will print a [successful response](#responses) when it finished parsing all commands in the file or encounters and `exit` command.
 Further output can be given by user-provided `echo` commands.
 
 ### Streaming input to the Ethos
 
 The `ethos` binary accepts input piped from stdin. The following are all equivalent ways of running `ethos`:
-```
+
+```shell
 % ethos <file>
 % ethos < <file>
 % cat <file> | ethos
 ```
 
-## Overview of Features
+## Overview of Eunoia's features
+
+Eunoia is the name of the logical framework and language that is supported natively by the Ethos checker.
+Although it is a general logical framework, Eunoia is geared towards defining proof systems used by SMT solvers and writing proofs in those systems.
 
-Eunoia is the name of the logical framework that is the native language accepted by the Ethos checker.
-Eunoia is a logical framework for defining proof rules and writing proofs from SMT solvers. Eunoia files typically are given the suffix `*.eo`.
+Eunoia files are text file that are typically given the suffix `*.eo`.
 
 The core features of Eunoia include:
-- Support for SMT-LIB version 3.0 syntax for defining theory signatures.
-- Support for associating syntactic categories (as specified by SMT-LIB e.g. `<numeral>`) with types.
-- A command `declare-rule` for defining proof rules.
-- A set of commands for specifying proofs (`step`, `assume`, and so on), whose syntax closely follows the Alethe proof format (for details see [here](https://verit.gitlabpages.uliege.be/alethe/specification.pdf)).
-- A library of operations (`eo::add`, `eo::mul`, `eo::concat`, `eo::extract`) for performing computations over values.
-- A command `program` for defining side conditions as ordered list of rewrite rules.
-- A command `declare-oracle-fun` for user-provided oracles, that is, functions whose semantics are given by external binaries. Oracles can be used e.g. for modular proof checking.
-- Commands for file inclusion (`include`) and referencing (`reference`). The latter command can be used to specify the name of an `*.smt2` input file that the proof is associated with.
 
-In the following sections, we review these features in more detail. A full syntax for the commands is given at the end of this document.
+- A syntax and type system for defining theory signatures that follows those of SMT-LIB version 3.0.
+- Constructs for associating syntactic categories (as specified by SMT-LIB e.g. `<numeral>`) with types.
+- A command, `declare-rule`, for defining proof rules.
+- A set of commands for specifying proofs (`step`, `assume`, and so on), whose syntax closely follows that of the Alethe proof format (for details, see [here](https://verit.gitlabpages.uliege.be/alethe/specification.pdf)).
+- A set of built-in basic types and a library of operations (`eo::add`, `eo::mul`, `eo::concat`, `eo::extract`) for performing computations over values.
+  <!--CT It would be more consistent with the rest of the terminology to use `define-program` instead -->
+- A command, `program`, for defining side conditions as ordered list of rewrite rules.
+- A command, `declare-oracle-fun`, for defining external, user-provided oracles, that is, functions whose semantics are given by external binaries. Oracles can be used, e.g., for modular proof checking.
+- Commands for file inclusion (`include`) and referencing (`reference`). The latter command can be used to specify the name of an `*.smt2` input file that the proof is associated with.
 
+In the following sections, we describe these features in more detail. A full syntax for the commands is given at the end of this document.
 
-# Declaring theory signatures
+### Declaring theory signatures
 
-In Eunoia as in SMT-LIB version 3.0, a common BNF is used to specify terms, types and kinds.
-In this document, a *term* may denote an ordinary term, a type or a kind.
-Terms are composed of applications, built-in operators of the language (e.g. for performing computations, see [computation](#computation)), literals (see [literals](#literals)), and three kinds of atomic terms (*constants*, *variables*, and *parameters*) which we will describe in the following.
-A *function* is an atomic term having a function type.
-The standard `let` binder can be used for specifying terms that contain common subterms, which is treated as syntax sugar.
+In Eunoia, as in SMT-LIB version 3.0, a common BNF is used to specify _terms_ (expressions denoting values), _types_ (expressions denoting sets of values) and _kinds_ (expressions denoting sets of types).
+In this document, unless specified otherwise, we will use _term_ more generally to refer to a value term, a type, or a kind
+Terms are composed of applications, built-in operators of the language (e.g., for performing computations, see [computation](#computation)), literals (see [literals](#literals)), and three kinds of atomic terms (_constants_, _variables_, and _parameters_) which we describe in the following.
+A _function (symbol)_ is an atomic term having a function type, that is, a type of the form `(->... ...)`.
+The standard `let` binder can be used for specifying terms that contain common subterms,
+which is treated as syntax sugar.
+<!--CT This is to be discussed further since I am not clear that it is really treated as syntactic sugar. -->
 
-As mentioned, the core language of Eunoia does not assume any definitions of standard SMT-LIB theories.
+The core language of Eunoia does not have any builtin SMT-LIB theories.
 Instead, SMT-LIB theories may defined as Eunoia signatures.
-Specifically, the Eunoia language has the following builtin expressions:
+To enable that, the Eunoia language has the following builtin constants:
+
 - `Type`, denoting the kind of all types,
 - `->`, denoting the function type,
 - `_`, denoting (higher-order) function application,
 - `Bool`, denoting the Boolean type,
-- `true` and `false`, denoting values of type `Bool`.
+- `true` and `false`, denoting the two values of type `Bool`.
 
-> The core logic of the Ethos also uses several builtin types (e.g. `Proof` and `Quote`) which define the semantics of proof rules. These types are intentionally left hidden from the user. Details on these types can be found throughout this document. More details on the core logic of the Ethos can be found in a forthcoming publication.
+> __Note:__ The core logic of the Ethos also uses several builtin types (e.g. `Proof` and `Quote`) which define the semantics of proof rules. These types are intentionally to exposed to the Eunoia user. Details on then can be found throughout this document. More details on the core logic of the Ethos will be available in a forthcoming publication.
 
-In the following, we informally write BNF categories `<symbol>` to denote an SMT-LIB version 3.0 symbol, `<term>` to denote an SMT-LIB term and `<type>` to denote a term whose type is `Type`, `<typed-param>` has syntax `(<symbol> <type> <attr>*)` and binds `<symbol>` as a fresh parameter of the given type and attributes (if provided).
+In the following, we informally use the syntactic categories `<symbol>` to denote an SMT-LIB 3.0 symbol, `<term>` to denote an SMT-LIB term and `<type>` to denote a term whose type is `Type`. The syntactic category `<typed-param>` is defined, BNF-style, as `(<symbol> <type> <attr>*)`. It binds `<symbol>` as a fresh parameter of the given type and attributes (if provided).
 
 The following commands are supported for declaring and defining types and terms. The first set of commands are identical to those in SMT-LIB version 3.0:
+
 - `(declare-const <symbol> <type> <attr>*)` declares a constant named `<symbol>` whose type is `<type>`. Can be given an optional list of attributes (see [attributes](#attributes)).
-- `(declare-type <symbol> (<type>*))` declares a new type named `<symbol>` whose kind is given by the argument types and return type `Type`.
+<!-- Moved here because it is present in SMT-LIB 3 -->
+
+- `(declare-consts <lit-category> <type>)` declares the class of symbols denoted by the literal category to have the given type.
+
+- `(declare-type <symbol> (<type>*))` declares a new type constructor named `<symbol>` whose kind is `Type` if `<type>*` is empty. If `<type>*` is `<type_1> ... <type_n>`, then kind of `<symbol>` is `(-> <type_1> ... <type_n> Type)`.
+  <!-- Added-->
+  This is a derived command as it is a shorthand for
+  `(declare-const <symbol> Type)` if `<type>*` is empty, and for
+  `(declare-const <symbol> (-><type>* Type))` otherwise.
+
+<!--CT Do we really need `define-type`? -->
 - `(define-type <symbol> (<type>*) <type>)` defines `<symbol>` to be a lambda term whose type is given by the argument and return types.
 - `(declare-datatype <symbol> <datatype-dec>)` defines a datatype `<symbol>`, along with its associated constructors, selectors, discriminators and updaters.
+
 - `(declare-datatypes (<sort-dec>^n) (<datatype-dec>^n))` defines a list of `n` datatypes for some `n>0`.
+
 - `(exit)` causes the checker to immediately terminate.
+
 - `(reset)` removes all declarations and definitions and resets the global scope. This command is similar in nature to its counterpart in SMT-LIB.
 
 The Eunoia language contains further commands for declaring symbols that are not standard SMT-LIB version 3.0:
-- `(declare-consts <lit-category> <type>)` declares the class of symbols denoted by the literal category to have the given type.
+
 - `(define <symbol> (<typed-param>*) <term> <attr>*)`, defines `<symbol>` to be a lambda term whose arguments and body and given by the command, or the body if the argument list is empty. Note that in contrast to the SMT-LIB command `define-fun`, a return type is not provided. The provided attributes may instruct the checker to perform e.g. type checking on the given term see [type checking define](#tcdefine).
-- `(declare-parameterized-const <symbol> (<typed-param>*) <type> <attr>*)` declares a variable named `<symbol>` whose type is `<type>`.
 
-> Variables are internally treated the same as constants by the Ethos, but are provided as a separate category, e.g. for user signatures that wish to distinguish universally quantified variables from free constants. They also have a relationship with user-defined binders, see [binders](#binders), and can be accessed via the builtin operator `eo::var` (see [computation](#computation)).
+- `(declare-parameterized-const <symbol> (<typed-param>*) <type> <attr>*)` declares a globally scoped variable named `<symbol>` whose type is `<type>`.
 
-> Symbol overloading is supported, see [overloading](#overloading).
+> __Note:__ Variables are internally treated the same as constants by Ethos. However, but are provided as a separate category, e.g., for user signatures that wish to distinguish universally quantified variables from free constants. They also have a relationship with user-defined binders, see [binders](#binders), and can be accessed via the builtin operator `eo::var` (see [computation](#computation)).
 
-### Example: Basic Declarations
+> __Note:__ Symbol overloading is supported, see [overloading](#overloading).
 
-```
+#### Example: Basic Declarations
+
+```smt
 (declare-type Int ())
 (declare-const c Int)
 (declare-const f (-> Int Int Int))
@@ -113,34 +143,38 @@ The Eunoia language contains further commands for declaring symbols that are not
 (declare-const P (-> Int Bool))
 ```
 
-Since ethos does not assume any builtin definitions of SMT-LIB theories, definitions of standard symbols (such as `Int`) may be provided in Eunoia signatures. In the above example, `c` is declared to be a constant (0-ary) symbol of type `Int`. The symbol `f` is a function taking two integers and returning an integer.
+Since Ethos does not assume any builtin definitions of SMT-LIB theories, definitions of standard symbols (such as `Int`) may be provided in Eunoia signatures<!--CT How are they provided? And aren't integers builtin? -->. In the above example, symbol `c` is declared to be a constant (0-ary) symbol of type `Int`. The symbol `f` is a function taking two integers and returning an integer.
 
-Note that despite using different syntax in their declarations, the types of `f` and `g` in the above example are identical.
+Observe that despite using different syntax in their declarations, the types of `f` and `g` in the above example are identical as `->` is a right-associative binary type constructor.
 
-> In ethos, all functions are unary. In the above example, `(-> Int Int Int)` is internally treated as `(-> Int (-> Int Int))`. Correspondingly, applications of functions are curried, e.g. `(f a b)` is treated as `((f a) b)`, which in turn can be seen as `(_ (_ f a) b)` where `_` denotes higher-order function application.
+> __Note:__ In Eunoia, all functions are unary. In the above example, `(-> Int Int Int)` is internally treated as `(-> Int (-> Int Int))`. Correspondingly, applications of functions are curried, e.g. `(f a b)` is treated as `((f a) b)`, which in turn can be seen as `(_ (_ f a) b)` where `_` denotes higher-order function application.
 
-### Example: Basic Definitions
+#### Example: Basic Definitions
 
-```
-(declare-const not (-> Bool Bool))
+```smt
+(declare-const not (->Bool Bool))
 (define id ((x Bool)) x)
 (define notId ((x Int)) (not (id x)))
 ```
 
 In the example above, `not` is declared to be a unary function over Booleans. Two defined functions are given, the first being an identity function over Booleans, and the second returning the negation of the first.
 
-Since `define` commands are treated as macro definitions, in this example, `id` is mapped to the lambda term whose SMT-LIB version 3 syntax is `(lambda ((x Bool)) x)`.
+Since `define` commands are treated as (hygienic) macro definitions, in this example, `id` is mapped to the lambda term whose SMT-LIB version 3 syntax is `(lambda ((x Bool)) x)`.
 Furthermore, `notId` is mapped to the lambda term `(lambda ((x Bool)) (not x))`.
-In other words, the following file is equivalent to the one above after parsing:
-```
-(declare-const not (-> Bool Bool))
+In other words, the following sequence of commands is equivalent to the one above after parsing:
+
+<!--CT This is literally identical to the previous list of commands -->
+```smt
+(declare-const not (->Bool Bool))
 (define id ((x Bool)) x)
 (define notId ((x Int)) (not x))
 ```
 
-### Example: Polymorphic types
+#### Example: Polymorphic types
 
-```
+Eunoia supports the declaration of polymorphic types, that is, types depending on other types.
+
+```smt
 (declare-type Int ())
 (declare-type Array (Type Type))
 (declare-const a (Array Int Bool))
@@ -149,217 +183,213 @@ In other words, the following file is equivalent to the one above after parsing:
 (declare-const b (IntArray Bool))
 ```
 
-In the above example, we define the integer sort and the array sort, whose kind is `(-> Type Type Type)`.
+In the above example, we declare and integer type constructor of kind `Type` and array type constructor of kind is `(->Type Type Type)`.
+
+<!-- We should say something about the defines above -->
 
 Note the following declarations generate terms of the same type:
 
-```
+```smt
 (declare-type Array_v2 (Type Type))
-(declare-const Array_v3 (-> Type Type Type))
+(declare-const Array_v3 (->Type Type Type))
 ```
 
-## <a name="literals"></a>The :type attribute for definitions
+<a name="literals"></a>
+
+### The :type attribute for definitions
 
-To type check terms, define statements can be annotated with `:type <term>`.
+To type check terms, `define` statements can be annotated with `:type <term>`.
+<!-- We should motivate this feature. Why is it there? -->
 In particular:
-```
-(declare-const not (-> Bool Bool))
+
+```smt
+(declare-const not (->Bool Bool))
 (define notTrue () (not true) :type Bool)
 ```
-This indicates that the checker should compute the type of the term `(not true)`.
-If this is not the specified type (in this case `Bool`), an error will be thrown.
 
-## The :var and :implicit annotations
+This indicates that the checker compare the type it computed for the term `(not true)` and compare it with the specified type `Bool`. An error will be thrown if the two types are not identical.
+
+### The :var and :implicit annotations
 
 The Eunoia language uses the SMT-LIB version 3.0 attributes `:var <symbol>` and `:implicit` in term annotations for naming arguments of functions and specifying they are implicit.
 
-```
+```smt
 (declare-type Int ())
-(declare-const eq (-> (! Type :var T) T T Bool))
+(declare-const eq (->(! Type :var T) T T Bool))
 (define P ((x Int) (y Int)) (eq Int x y))
 ```
 
-The above example declares a predicate `eq` whose first argument is a type, that is given a name `T`. It then expects two terms of type `T` and returns a `Bool`. In the definition of `P`, this predicate is applied to two variables, where the type `Int` must be explicitly provided.
+The above example declares a predicate symbol `eq` whose first argument is a type, that is given a name `T`. It then expects two terms of type `T` and returns a `Bool`. In the definition of `P`, `eq` is applied to two variables, with type `Int` explicitly provided.
 
-```
+In contrast, the example below declares a predicate `=` where the type of the arguments is implicit (this corresponds to the SMT-LIB standard definition of `=`). In the definition of `P`, the type of the arguments `Int` is not provided.
+
+```smt
 (declare-type Int ())
-(declare-const = (-> (! Type :var T :implicit) T T Bool))
+(declare-const = (->(! Type :var T :implicit) T T Bool))
 (define P ((x Int) (y Int)) (= x y))
 ```
 
-In contrast, the above example declares a predicate `=` where the type of the arguments is implicit (this corresponds to the SMT-LIB standard definition of equality). In the definition of `P`, the type of the arguments `Int` does not need to be provided.
-
-We call `T` in the above definitions a *parameter*. The free parameters of the return type of an expression should be contained in at least one non-implicit argument. In particular, the following declaration is malformed, since the return type of `f` cannot be inferred from its arguments:
+<!--CT Added -->
+In general, an argument can be made implicit if its value can be inferred from the type of later arguments.
 
+We call `T` in the above definitions a _parameter_. The free parameters of the return type of an expression should be contained in at least one non-implicit argument. In particular, the following declaration is malformed, since the return type of `f` cannot be inferred from its arguments:
 
-```
+```smt
 (declare-type Int ())
-(declare-const f (-> (! Type :var T :implicit) Int T))
+(declare-const f (->(! Type :var T :implicit) Int T))
 ```
 
-> Internally, `(! T :var t)` is syntax sugar for the type `(Quote t)` where `t` is a parameter of type `T` and `Quote` is a distinguished type of kind `(-> (! Type :var U) U Type)`. When type checking applications of functions of type `(-> (Quote t) S)`, the parameter `t` is bound to the argument the function is applied to.
+> __Note:__ Internally, `(! T :var t)` is syntax sugar for the type `(Quote t)` where `t` is a parameter of type `T` and `Quote` is a distinguished type of kind `(->(! Type :var U) U Type)`. When type checking applications of functions of type `(->(Quote t) S)`, the parameter `t` is bound to the argument the function is applied to.
 
-> Internally, `(! T :implicit)` drops `T` from the list of arguments of the function type we are defining.
+> __Note:__ Internally, `(! T :implicit)` drops `T` from the list of arguments of the function type we are defining.
 
-## The :requires annotation
+### The :requires annotation
 
 Arguments to functions can also be annotated with the attribute `:requires (<term> <term>)` to denote a equality condition that is required for applications of the term to type check.
 
-```
+```smt
 (declare-type Int ())
-(declare-const BitVec (-> (! Int :var w :requires ((eo::is_neg w) false)) Type))
+(declare-const BitVec (->(! Int :var w :requires ((eo::is_neg w) false)) Type))
 ```
-The above declares the integer sort and the bitvector sort that expects a non-negative integer `w`.
+The above declares the integer type `Int` and a bitvector type constructor `BitVec` that expects a _non-negative integer_ `w`.
+In detail, the first argument of `BitVec` is supposed to be an `Int` value and is named `w` via the `:var` attribute.
+The second annotation indicates that the term `(eo::is_neg w)` must evaluate to `false` at type checking type.
+Symbol `eo::is_neg` denotes a builtin function that returns `true` if its argument is a negative numeral, and returns false otherwise (for details, see [computation](#computation)).
+<!-- This needs discussion, what is the input type of `eo::is_neg`? How can `eo::is_neg` accept a value of a user-defined type `Int` given that it is builtin?  -->
 
-In detail, the first argument of `BitVec` is an integer sort, which is named `w` via `:var`.
-The second annotation indicates that `(eo::is_neg w)` must evaluate to `false`, where note that `eo::is_neg` returns `true` if and only if its argument is a negative numeral (for details, see [computation](#computation)).
+> __Note:__ Internally, `(! T :requires (t s))` is syntax sugar for the type term `(eo::requires t s T)` where `eo::requires` is an operator that evaluates to its third argument if and only if its first two arguments are _computationally_ equivalent (details on this operator are given in [computation](#computation))<!--CT This is non-ideal from a language design point of view as it makes the semantic of Eunoia non-compositional: the meaning of `eo::requires` applications changes depending on whether there are in positive or negative positions. -->.
+Furthermore, the function type `(->(eo::requires t s T) S)` is treated as `(->T (eo::requires t s S))`. Ethos rewrites all types of the former form to the latter.
 
-> Internally, `(! T :requires (t s))` is syntax sugar for `(eo::requires t s T)` where `eo::requires` is an operator that evalutes to its third argument if and only if its first two arguments are equivalent (details on this operator are given in [computation](#computation)). Furthermore, the function type `(-> (eo::requires t s T) S)` is treated as `(-> T (eo::requires t s S))`. The Ethos rewrites all types of the former to the latter.
+<a name="attributes"></a>
 
-## <a name="opaque"></a>The :opaque annotation
+### Declarations with attributes
 
-The attribute `:opaque` can be used to denote that a distinguished argument to a function.
-In particular, functions with opaque arguments intuitively can be considered a *family* of functions indexed by their opaque arguments.
-An example of this annotation is the following:
-
-```
-(declare-type Array (Type Type))
-(declare-const @array_diff
-   (-> (! Type :var T :implicit) (! Type :var U :implicit)
-   (! (Array T U) :opaque)
-   (! (Array T U) :opaque)
-   T))
-
-(declare-type Int ())
-(declare-const A (Array Int Int))
-(declare-const B (Array Int Int))
-(define d () (@array_diff A B) :type Int)
-```
+The Eunoia language supports term annotations on declared constants, which for instance allow the user to treat a constant as being variadic, i.e. taking an arbitrary number of arguments. The available annotations for this purpose are:
 
-The above example declares a function `@array_diff` symbol. 
-This has two implicit type arguments `T` and `U` followed by two opaque array arguments and has `T` as a return type.
-In the remainder of the example, we define `d` to be this function applied to the arrays `A` and `B`, where `d` has type `Int`.
+- `:right-assoc` (resp. `:left-assoc`) denoting that application of the declared binary constant to more than two terms are to be treated as right (resp. left) associative,
 
-Intuitively, `d` should be considered an atomic constant symbol, where `A` and `B` are its indices and not its children.
-In particular, this means that any computation that pattern matches `d` will not consider it to be a function application.
-We give examples of this later in [ex-substitution](#ex-substitution).
+- `:right-assoc-nil <symbol>` (resp. `:left-assoc-nil <symbol>`) denoting that applications of the declared binary constant to one or more terms are to be treated as right (resp. left) associative, with the given `<symbol>` used as an additional rightmost (resp. leftmost) argument.
+<!--CT Do we really want to restrict the nil element to be a symbol, as opposed to a term? -->
 
-Functions can have both opaque and ordinary arguments, where the opaque arguments are expected to come first.
-The concatentation of the expected arguments can be passed to the symbol in the order they are given.
-For example:
-```
-(declare-type Int ())
-(declare-const @purify_fun (-> (! (-> Int Int) :opaque) Int Int))
+- `:chainable <symbol>` denoting that the arguments of the declared binary constant are chainable using the (binary) operator given by `<symbol>`,
 
-(declare-const f (-> Int Int))
-(declare-const a Int)
-(define d () (@purify_fun f a) :type Int)
-```
-In this example, `@purify_fun` is declared as a function with one opaque argument, and ordinary integer argument, and returns an integer.
-Intuitively, this definition is introducing a new function, indexed by a function, that is of type `(-> Int Int)`.
-After parsing, the term `(@purify_fun f a)` is a function application whose operator is `(@purify_fun f)` and has a single child `a`.
-
-> Opaque arguments should always be expected before other arguments. Otherwise all applications of the given function will be ill-typed.
-
-## <a name="attributes"></a>Declarations with attributes
-
-The Eunoia language supports term annotations on declared constants, which for instance can allow the user to treat a constant as being variadic, i.e. taking an arbitrary number of arguments. The available annotations in the Ethos for this purpose are:
-- `:right-assoc` (resp. `:left-assoc`) denoting that the declared constant is right (resp. left) associative,
-- `:right-assoc-nil <symbol>` (resp. `:left-assoc-nil <symbol>`) denoting that the declared constant is right (resp. left) associative with the given nil terminator given by `<symbol>`,
-- `:chainable <symbol>` denoting that the arguments of the declared constant are chainable using the (binary) operator given by `<symbol>`,
 - `:pairwise <symbol>` denoting that the arguments of the declared constant are treated pairwise using the (binary) operator given by `<symbol>`.
+
 - `:binder <symbol>` denoting that the first argument of the declared constant can be provided using a syntax for variable lists whose constructor is the one provided by `<symbol>`.
+
 A declared function can be marked with at most one of the above attributes or an error is thrown.
 
-A parameter may be marked with the following attributes:
+A parameter in a function symbol declaration may be marked with the following attribute:
+
 - `:list`, denoting that the parameter should be treated as a list when appearing as a child of an application of a right (left) associative operator.
 
-### Right/Left associative
+#### Right/Left associative
 
-```
-(declare-const or (-> Bool Bool Bool) :right-assoc)
+```smt
+(declare-const or (->Bool Bool Bool) :right-assoc)
 (define P ((x Bool) (y Bool) (z Bool)) (or x y z))
 (define Q ((x Bool) (y Bool)) (or x y))
 (define R ((x Bool)) (or x))
 ```
 
-In the above example, `(or x y z)` is syntax sugar for `(or x (or y z))`.
+In the above example, `(or x y z)` is treated as `(or x (or y z))`.
 The term `(or x y)` is not impacted by the annotation `:right-assoc` since it has fewer than 3 children.
-The term `(or x)` is also not impacted by the annotation, and denotes the partial application of `or` to `x`, whose type is `(-> Bool Bool)`.
+The term `(or x)` is also not impacted by the annotation, and denotes the _partial application_ of `or` to `x`, whose type is `(->Bool Bool)`.
 
 Left associative can be defined analogously:
-```
-(declare-const and (-> Bool Bool Bool) :left-assoc)
+
+```smt
+(declare-const and (->Bool Bool Bool) :left-assoc)
 (define P ((x Bool) (y Bool) (z Bool)) (and x y z))
 ```
-In the above example, `(and x y z)` is syntax sugar for `(and (and x y) z)`.
 
-Note that the type for right and left associative operators is typically `(-> T T T)` for some `T`.
+In the above example, `(and x y z)` is treated as `(and (and x y) z)`.
+
+Note that the type for right and left associative operators is typically `(->T T T)` for some type `T`. <!--CT Added. Is this the case in Ethos? -->More generally, a constant declared with the `:right-associative` annotation must have a type of the form `(->T1 T2 T2)` for some types `T1` and `T2`. Similarly, a constant declared with the `:left-associative` annotation must have a type of the form `(->T1 T2 T1)`.
 
-### <a name="assoc-nil"></a>Right/Left associative with nil terminator
+<a name="assoc-nil"></a>
+
+#### Right/Left associative with nil terminator
 
 Eunoia supports a variant of the aforementioned functionality where a (ground) nil terminator is provided.
 
-```
-(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
+```smt
+(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
 (define P ((x Bool) (y Bool) (z Bool)) (or x y z))
 (define Q ((x Bool) (y Bool)) (or x y))
 (define R ((x Bool) (y Bool)) (or x))
 ```
 
-In the above example, `(or x y z)` is syntax sugar for `(or x (or y (or z false)))`,
-`(or x y)` is syntax sugar for `(or x (or y false))`,
-and `(or x)` is syntax sugar for `(or x false)`.
+In the above example, `(or x y z)` is treated as `(or x (or y (or z false)))`,
+`(or x y)` is treated as `(or x (or y false))`,
+and `(or x)` is treated as `(or x false)`.
+<!--CT added -->In contrast, if `or` was annotated with `left-associative-nil`,
+`(or x y z)` would be treated as `(or (or (or false x) y) z)`,
+`(or x y)` as `(or (or false x) y)`,
+and `(or x)` as `(or false x)`.
 
-The advantage of right (resp. left) associative operators nil terminators is that the terms they specify are unambiguous, in constrast to operators without nil terminators.
+The advantage of right or left associative operators with nil terminators is that the terms they specify are unambiguous, which is not the case for right or left associative operators without nil terminators.
 In particular, note the following example:
 
-```
-(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
+```smt
+(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
 (define P ((x Bool) (y Bool) (z Bool)) (or x (or y z)))
 (define Q ((x Bool) (y Bool) (z Bool)) (or x y z))
 ```
 
-If `or` would have been marked `:right-assoc`, then the definition of both `P` and `Q` would be `(or x (or y z))` after desugaring.
+<!--CT I do not think this is a cogent example since `(or x (or y z)))` and `(or x (or y z)))` are semantically equivalent anyway given that `false` is a neutral element for `or`. The difference would be clearer with a nil element that was not also a neutral element. 
+
+For instance, with
+(declare-const + (-> Int Int Int) :right-assoc-nil 1)
+We have that 
+(+ x (+ y z))) = (+ x (+ (+ y (+ z 1)) 1)) = x + y + z + 2
+is not equivalent to
+(+ x (+ y (+ z 1))) = x + y + z + 1
+However, I would use this example not to argue that it is advantageous to use the :[left|right]-associative-nil annotation but to warn the reader that the nil element better be a left/right identity for the binary operator, otherwise the semantic is highly unintuitive.
+-->
+
+If `or` had been marked `:right-assoc`, then the definition of both `P` and `Q` would be `(or x (or y z))` after desugaring.
 In contrast, marking `or` with `:right-assoc-nil false` leads to the distinct terms `(or x (or (or y (or z false)) false))` and `(or x (or y (or z false)))` after desugaring.
 
 Right and left associative operators with nil terminators also have a relationship with list terms (as we will see in the following section), and in computational operators.
 
-The type for right and left associative operators with nil terminators is typically `(-> T T T)` for some `T`, where their nil terminator has type `T`.
+The type for right and left associative operators with nil terminators is typically `(->T T T)` for some `T`, where their nil terminator has type `T`. <!--CT Added. Is it the case in Ethos? -->More generally, a constant declared with the `:right-associative-nil` annotation must have a type of the form `(->T1 T2 T2)` where `T2` is the type of the nil constant, for some types `T1` and `T2`. Similarly, a constant declared with the `:left-associative` annotation must have a type of the form `(->T1 T2 T1)` where `T1` is the type of the nil constant.
 
 The nil terminator of a right associative operator may involve previously declared symbols in the signature.
 For example:
 
-```
+```smt
 (declare-type RegLan ())
 (declare-const re.all RegLan)
-(declare-const re.inter (-> RegLan RegLan RegLan) :right-assoc-nil re.all)
+(declare-const re.inter (->RegLan RegLan RegLan) :right-assoc-nil re.all)
 ```
 
-This example defines the constant `re.all` (in SMT-LIB, this is the regular expression accepting all strings)
+This example defines the constant `re.all` (in SMT-LIB, this is the regular expression generating the set of all strings)
 and the function `re.inter` (in SMT-LIB, the intersection of regular expressions), where the latter is defined to have a nil terminator
 that references the free constant `re.all`.
 
 However, when using `declare-const`, the nil terminator of an associative operator cannot depend on the parameters of the type of that function.
-For example, say we wish to declare bitvector-or (`bvor` in SMT-LIB), where its nil terminator is bitvector zero for the given bitwidth.
+For example, say we wish to declare bitvector or (`bvor` in SMT-LIB), where its nil terminator is bitvector zero for the given bit width.
 A possible declaration is the following:
-```
+
+```smt
 (declare-const bvor
-    (-> (! Int :var m :implicit) (BitVec m) (BitVec m) (BitVec m))
+    (->(! Int :var m :implicit) (BitVec m) (BitVec m) (BitVec m))
     :right-assoc-nil ???
 )
 ```
+
 The nil terminator of this operator is the bitvector zero whose width is `m`.
 However note that `m` is not in scope of the declaration of its nil terminator.
 We instead require such declarations to be made with `declare-parameterized-const`, which we will describe later in [param-constants](#param-constants).
 
-### List
+#### List
 
-Atomic terms can be marked with the annotation `:list`.
+Atomic terms can be marked with the annotation `:list`.<!--CT Do we really need this level of generality? Can we restrict the annotation to just function arguments or perhaps just typed vars? -->
 This annotation marks that the term should be treated as a list of arguments when it occurs as an argument of a right (left) associative operator with a nil element. Note the following example:
 
-```
-(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
+```smt
+(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
 (define P ((x Bool) (y Bool)) (or x y))
 (define Q ((x Bool) (y Bool :list)) (or x y))
 (declare-const a Bool)
@@ -371,7 +401,7 @@ This annotation marks that the term should be treated as a list of arguments whe
 In the above example, note that `or` has been marked `:right-assoc-nil false`.
 As before, the definition of `P` is syntax sugar for `(or x (or y false))`.
 In contrast, the definition of `Q` is simply `(or x y)`, since `y` has been marked with `:list`.
-Conceptually, our definition of `P` treats `y` as the second child of an `or` term, whereas our definition of `Q` treats `y` as the *tail* of an `or` term.
+Conceptually, our definition of `P` treats `y` as the second child of an `or` term, whereas our definition of `Q` treats `y` as the _tail_ of an `or` term.
 
 Then, `P` and `Q` are both applied to the pair of arguments `a` and `(or a b)`.
 In the former (i.e. `Paab`), the definition is equivalent after desugaring to `(or a (or (or a (or b false)) false))`, whereas in the latter (i.e. `Qaab`) the definition is equivalent after desugaring to `(or a (or a (or b false)))`.
@@ -389,8 +419,8 @@ For each term `ti` we process, the returned term `r` is updated to `(f ti r)` if
 if `ti` is marked with `:list`.
 Examples of this desugaring are given below.
 
-```
-(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
+```smt
+(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
 (define test ((x Bool) (y Bool) (z Bool :list) (w Bool :list))
     (and
         (or x y)        ; (or x (or y false))
@@ -405,11 +435,11 @@ Examples of this desugaring are given below.
 Note that in the case of `(or z)`, no application of `or` is constructed, since only one argument term is given, since it is marked with `:list`.
 In contrast, `(or x)` denotes the `or` whose children are `x` and `false`.
 
-### Chainable
+#### Chainable
 
-```
+```smt
 (declare-type Int ())
-(declare-const and (-> Bool Bool Bool) :right-assoc)
+(declare-const and (->Bool Bool Bool) :right-assoc)
 (declare-const >= (-> Int Int Bool) :chainable)
 (define ((x Int) (y Int) (z Int)) (>= x y z))
 (define Q ((x Int) (y Int)) (>= x y))
@@ -418,29 +448,38 @@ In contrast, `(or x)` denotes the `or` whose children are `x` and `false`.
 In the above example, `(>= x y z w)` is syntax sugar for `(and (>= x y) (>= y z))`,
 whereas the term `(>= x y)` is not impacted by the annotation `:chainable` since it has fewer than 3 children.
 
-Note that the type for chainable operators is typically `(-> T T S)` for some types `T` and `S`,
-where the type of its chaining operator is `(-> S S S)`, and that operator has been as variadic via some attribute (e.g. `:right-assoc`).
+Note that the type for chainable operators is typically `(->T T S)` for some types `T` and `S`,
+where the type of its chaining operator is `(->S S S)`, and that operator has been as variadic via some attribute (e.g. `:right-assoc`).
 
-### Pairwise
+#### Pairwise
 
-```
+```smt
 (declare-type Int ())
-(declare-const and (-> Bool Bool Bool) :right-assoc)
-(declare-const distinct (-> (! Type :var T :implicit) T T Bool) :pairwise and)
+(declare-const and (->Bool Bool Bool) :right-assoc)
+(declare-const distinct (->(! Type :var T :implicit) T T Bool)
+ :pairwise and)
 (define P ((x Int) (y Int) (z Int)) (distinct x y z))
 ```
-In the above example, `(distinct x y z)` is syntax sugar for `(and (distinct x y) (distinct x z) (distinct y z))`.
 
-Note that the type for chainable operators is typically `(-> T T S)` for some types `T` and `S`,
-where the type of its pairwise operator is `(-> S S S)`, and that operator has been as variadic via some attribute.
+In the above example, `(distinct x y z)` is treated as `(and (distinct x y) (distinct x z) (distinct y z))`.
 
-### <a name="binders"></a>Binder
-```
+Note that the type for chainable operators is typically `(->T T S)` for some types `T` and `S`,
+where the type of its pairwise operator is `(->S S S)`,
+and that operator has been as variadic via some attribute<!--CT I do not understand this sentence -->.
+
+<a name="binders"></a>
+
+#### Binder
+
+<!--CT Section to be reviewed further -->
+
+```smt
 (declare-type Int ())
 (declare-type @List ())
 (declare-const @nil @List)
-(declare-const @cons (-> (! Type :var T :implicit) T @List @List) :right-assoc-nil @nil)
-(declare-const forall (-> @List Bool Bool) :binder @cons)
+(declare-const @cons (->(! Type :var T :implicit) T @List @List)
+ :right-assoc-nil @nil)
+(declare-const forall (->@List Bool Bool) :binder @cons)
 (declare-const P (-> Int Bool))
 
 (define Q1 () (forall ((x Int)) (P x)))
@@ -450,6 +489,7 @@ where the type of its pairwise operator is `(-> S S S)`, and that operator has b
 (define x () (eo::var "x" Int))
 (define Q4 () (forall (@cons x) (P x)))
 ```
+
 In the above example, `forall` is declared as a binder.
 This indicates that the parser (optionally) accepts a variable list as the first argument when parsing applications of `forall` instead of a term.
 In particular, in the last two commands, the parser accepts `(forall ((x Int)) (P x))` for the variable list containing `x`.
@@ -457,20 +497,20 @@ A variable list parsed in this way binds the symbol `x` to a variable of type `I
 The variable list passed as the first argument to the binder is determined by applying the specified constructor (in this case `@cons`) to the list of variables, so that `(forall ((x Int)) (P x))` is syntax sugar for `(forall (@cons x) (P x))`.
 The constructor specified in declarations of binders should accept a variable number of arguments, e.g. `@cons` is declared with attribute `:right-assoc-nil`.
 
-Variables introduced when parsing binders are always the same for each (symbol, type) pair.
+Variables introduced when parsing binders are always the same for each (symbol, type) pair unless the option `--binder-fresh` is enabled, in which case the variable is always unique.
 In particular, this means that the definitions of `Q1` and `Q2` are syntactically identical in the above example.
 On the other hand, the definition `Q3` is distinct from both of these, since `y` is a distinct variable from `x`.
 
 Furthermore, note that a binder also may accept an explicit term as its first argument.
 In the above example, `Q4` has `(@cons x)` as its first argument, where `x` was explicitly defined as a variable.
-This means that the definition of `Q4` is also syntactically equivalent to the definition of `Q1` and `Q2`.
+This means that the definition of `Q4` is also syntactically equivalent to the definition of `Q1` and `Q2`, again assuming that `--binder-fresh` is not enabled.
 
-Note that if the option `--binder-fresh` is enabled, then when parsing reference files, the variables in binders are always fresh.
-This option does not impact how binders are parsed in Eunoia files.
+<a name="literals"></a>
 
-## <a name="literals"></a>Literal types
+### Literal types
 
 The Eunoia language supports associating SMT-LIB version 3.0 syntactic categories with types. In detail, a syntax category is one of the following:
+
 - `<numeral>` denoting the category of numerals `-?<digit>+`,
 - `<decimal>` denoting the category of decimals `-?<digit>+.<digit>+`,
 - `<rational>` denoting the category of rationals `-?<digit>+/<digit>+`,
@@ -478,10 +518,8 @@ The Eunoia language supports associating SMT-LIB version 3.0 syntactic categorie
 - `<hexadecimal>` denoting the category of hexadecimal constants `#x<hex-digit>+` where hexdigit is `[0-9] | [a-f] | [A-F]`,
 - `<string>` denoting the category of string literals `"<char>*"`.
 
-When parsing proofs and reference files, by default, decimal literals will be treated as syntax sugar for rational literals unless the option `--no-normalize-dec` is enabled.
+By default, decimal literals will be treated as syntax sugar for rational literals unless the option `--no-normalize-dec` is enabled.
 Similarly, hexadecimal literals will be treated as syntax sugar for binary literals unless the option `--no-normalize-hex` is enabled.
-Some SMT-LIB logics (e.g. `QF_LRA`) state that numerals should be treated as syntax sugar for rational literals.
-This behavior can be enabled when parsing proofs and reference files using the option `--normalize-num`.
 
 In contrast to SMT-LIB version 2, note that rational values can be specified directly using the syntax `5/11, 2/4, 0/1` and so on.
 Rationals are normalized so that e.g. `2/4` and `1/2` are syntactically equivalent after parsing.
@@ -493,16 +531,17 @@ Also note in contrast to SMT-LIB version 2, negative arithmetic can be provided
 String values use the standard escape sequences as specified in SMT-LIB version 2.6, namely `""` within a string literal denotes `"`.
 The only other escape sequences are of the form `\u{dn ...d1}` for `1<=n<=5` and `\u d4 d3 d2 d1` for hexadecimal digits `d1...d5` where `d5` is in the range `[0-2]`.
 
-> Numeral, rational and decimal values are implemented by the arbtirary precision arithmetic library GMP.
-Binary and hexadecimal values are implemented as layer on top of numeral values that tracks a bitwidth.
-String values are implemented as a vector of unsigned integers whose maximum value is specified by SMT-LIB version 2.6, namely the character set corresponds to Unicode values 0 to 196607.
+> __Note:__ Numeral, rational and decimal values are implemented by the arbitrary precision arithmetic library GMP. Binary and hexadecimal values are implemented as layer on top of numeral values that tracks a bit width. String values are implemented as a vector of unsigned integers whose maximum value is specified by SMT-LIB version 2.6, namely the character set corresponds to Unicode values 0 to 196607.
+
+> __Note:__ The user is not required to declare that `true` and `false` are values of type `Bool`. Instead, it is assumed that the syntactic category `<boolean>` of Boolean values (`true` and `false`) has been associated with the Boolean sort. In other words, `(declare-consts <boolean> __Note:__Bool)` is a part of the builtin signature assumed by Ethos.
 
-> Note that the user is not required to declare that `true` and `false` are values of type `Bool`. Instead, it is assumed that the syntactic category `<boolean>` of Boolean values (`true` and `false`) has been associated with the Boolean sort. In other words, `(declare-consts <boolean> Bool)` is a part of the builtin signature assumed by Ethos.
+<a name="declare-consts"></a>
 
-### <a name="declare-consts"></a>Declaring classes of literals
+#### Declaring classes of literals
 
 The following gives an example of how to define the class of numeral constants.
-```
+
+```smt
 (declare-type Int ())
 (declare-consts <numeral> Int)
 (define P ((x Int)) (> x 7))
@@ -511,11 +550,13 @@ The following gives an example of how to define the class of numeral constants.
 In the above example, the `declare-consts` command specifies that numerals (`1`, `2`, `3`, and so on) are constants of type `Int`.
 The signature can now refer to arbitrary numerals in definitions, e.g. `7` in the definition of `P`.
 
-> Internally, the command above only impacts the type rule assigned to numerals that are parsed. Furthermore, the Ethos internally distinguishes whether a term is a numeral value, independently of its type, for the purposes of computational operators (see [computation](#computation)).
+> __Note:__ Internally, the command above only impacts the type rule assigned to numerals that are parsed. Furthermore, the Ethos internally distinguishes whether a term is a numeral value, independently of its type, for the purposes of computational operators (see [computation](#computation)).
 
-> For specifying literals whose type rule varies based on the content of the constant, the Eunoia language uses a distinguished variable `eo::self` which can be used in `declare-consts` definitions. For an example, see the type rule for SMT-LIB bit-vector constants, described later in [bv-literals](#bv-literals).
+> __Note:__ For specifying literals whose type rule varies based on the content of the constant, the Eunoia language uses a distinguished variable `eo::self` which can be used in `declare-consts` definitions. For an example, see the type rule for SMT-LIB bit-vector constants, described later in [bv-literals](#bv-literals).
 
-# <a name="computation"></a>Computational Operators in ethos
+<a name="computation"></a>
+
+## Computational Operators
 
 The Ethos has builtin support for computations over all syntactic categories of SMT-LIB version 3.0.
 We list the operators below, roughly categorized by domain.
@@ -524,9 +565,9 @@ For example, `eo::add` returns the result of adding two integers or rationals, b
 Similarly, `eo::concat` returns the result of concatenating two string literals, but can also concatenate binary constants.
 We remark on the semantics in the following.
 
-In the following, we say a term is *ground* if it contains no parameters as subterms.
-We say an *arithmetic value* is a numeral, decimal or rational value.
-We say a *bitwise value* is a binary or hexadecimal value.
+In the following, we say a term is _ground_ if it contains no parameters as subterms.
+We say an _arithmetic value_ is a numeral, decimal or rational value.
+We say a _bitwise value_ is a binary or hexadecimal value.
 A 32-bit numeral value is a numeral value between `0` and `2^32-1`.
 Binary values are considered to be in little endian form.
 
@@ -535,104 +576,131 @@ For these operators, we provide the equivalent formulation.
 A signature defining these files can be found in [non-core-eval](#non-core-eval).
 Note however that the evaluation of these operators is handled by more efficient methods internally in the Ethos, that is, they are not treated as syntax sugar internally.
 
-Core operators:
+### Core operators
+
 - `(eo::is_eq t1 t2)`
-    - Returns `true` if `t1` is (syntactically) equal to `t2`, or `false` if `t1` and `t2` are distinct and ground. Otherwise, it does not evaluate.
+  - Returns `true` if `t1` is (syntactically) equal to `t2`, or `false` if `t1` and `t2` are distinct and ground. Otherwise, it does not evaluate.
+
+ <!--CT To be discussed with Andy
+    $$[(\textsf{eo::is_eq}\ t_1\ t_2)] =
+    \begin{cases}
+     \textsf{true} & \text{if } [t_1], [t_2] \text{ are identical} \\
+     \textsf{false} & \text{if } [t_1], [t_2] \text{ are distinct and ground} \\
+     (\textsf{eo::is_eq}\ t_1\ t_2) & \text{otherwise}
+    \end{cases}
+    $$
+-->
+
 - `(eo::ite t1 t2 t3)`
-    - Returns `t2` if `t1` evaluates to `true`, `t3` if `t2` evaluates to `false`, and is not evaluated otherwise. Note that the branches of this term are only evaluated if they are the return term.
+  - Returns `t2` if `t1` evaluates to `true`, `t3` if `t2` evaluates to `false`, and is not evaluated otherwise. Note that the branches of this term are only evaluated if they are the return term.
+
+ <!--CT To be discussed with Andy
+    $$[(\textsf{eo::ite}\ t_1\ t_2\ t_3)] =
+    \begin{cases}
+     [t_2] & \text{if } [t_1] = \textsf{true} \\
+     [t_3] & \text{if } [t_1] = \textsf{false} \\
+     (\textsf{eo::ite}\ t_1\ t_2\ t_3) & \text{otherwise}
+    \end{cases}
+    $$
+-->
+
 - `(eo::requires t1 t2 t3)`
-    - Returns `t3` if `t1` is (syntactically) equal to `t2`, and is not evaluated otherwise.
+  - Returns `t3` if `t1` is (syntactically) equal to `t2`, and is not evaluated otherwise.
 - `(eo::hash t1)`
-    - If `t1` is a ground term, this returns a numeral that is unique to `t1`.
+  - If `t1` is a ground term, this returns a numeral that is unique to `t1`.
 - `(eo::typeof t1)`
-    - If `t1` is a ground term, this returns the type of `t1`.
+  - If `t1` is a ground term, this returns the type of `t1`.
 - `(eo::nameof t1)`
-    - If `t1` is a ground constant or variable, this returns the name of `t1`, i.e. the string corresponding to the symbol it was declared with.
+  - If `t1` is a ground constant or variable, this returns the name of `t1`, i.e. the string corresponding to the symbol it was declared with.
 - `(eo::var t1 t2)`
-    - If `t1` is a string value and `t2` is ground type, this returns the variable whose name is `t1` and whose type is `t2`.
+  - If `t1` is a string value and `t2` is ground type, this returns the variable whose name is `t1` and whose type is `t2`.
 - `(eo::cmp t1 t2)`
-    - Equivalent to `(eo::is_neg (eo::add (eo::neg (eo::hash t1)) (eo::hash t2)))`. Note that this method corresponds to an arbitrary total order on terms.
+  - Equivalent to `(eo::is_neg (eo::add (eo::neg (eo::hash t1)) (eo::hash t2)))`. Note that this method corresponds to an arbitrary total order on terms.
 - `(eo::is_z t)`
-    - Equivalent to `(eo::is_eq (eo::to_z t) t)`.
+  - Equivalent to `(eo::is_eq (eo::to_z t) t)`.
 - `(eo::is_q t)`
-    - Equivalent to `(eo::is_eq (eo::to_q t) t)`. Note this returns false for decimal literals.
+  - Equivalent to `(eo::is_eq (eo::to_q t) t)`. Note this returns false for decimal literals when `--no-normalize-dec` is enabled.
 - `(eo::is_bin t)`
-    - Equivalent to `(eo::is_eq (eo::to_bin (eo::len t) t) t)`. Note this returns false for hexadecimal literals.
+  - Equivalent to `(eo::is_eq (eo::to_bin (eo::len t) t) t)`. Note this returns false for hexadecimal literals  when `--no-normalize-hex` is enabled.
 - `(eo::is_str t)`
-    - Equivalent to `(eo::is_eq (eo::to_str t) t)`.
+  - Equivalent to `(eo::is_eq (eo::to_str t) t)`.
 - `(eo::is_bool t)`
-    - Equivalent to `(eo::or (eo::is_eq t true) (eo::is_eq t false))`.
+  - Equivalent to `(eo::or (eo::is_eq t true) (eo::is_eq t false))`.
 - `(eo::is_var t)`
-    - Equivalent to `(eo::is_eq (eo::var (eo::nameof t) (eo::typeof t)) t)`.
+  - Equivalent to `(eo::is_eq (eo::var (eo::nameof t) (eo::typeof t)) t)`.
+
+### Boolean operators
 
-Boolean operators:
 - `(eo::and t1 t2)`
-    - Boolean conjunction if `t1` and `t2` are Boolean values (`true` or `false`).
-    - Bitwise conjunction if `t1` and `t2` are bitwise values of the same category and bitwidth.
+  - Boolean conjunction if `t1` and `t2` are Boolean values (`true` or `false`).
+  - Bitwise conjunction if `t1` and `t2` are bitwise values of the same category and bitwidth.
 - `(eo::or t1 t2)`
-    - Boolean disjunction if `t1` and `t2` are Boolean values.
-    - Bitwise disjunction if `t1` and `t2` are bitwise values of the same category and bitwidth.
+  - Boolean disjunction if `t1` and `t2` are Boolean values.
+  - Bitwise disjunction if `t1` and `t2` are bitwise values of the same category and bitwidth.
 - `(eo::xor t1 t2)`
-    - Boolean xor if `t1` and `t2` are Boolean values.
-    - Bitwise xor if `t1` and `t2` are bitwise values of the same category and bitwidth.
+  - Boolean xor if `t1` and `t2` are Boolean values.
+  - Bitwise xor if `t1` and `t2` are bitwise values of the same category and bitwidth.
 - `(eo::not t1)`
-    - Boolean negation if `t1` is a Boolean value.
-    - Bitwise negation if `t1` is a bitwise value.
-    
-Arithmetic operators:
+  - Boolean negation if `t1` is a Boolean value.
+  - Bitwise negation if `t1` is a bitwise value.
+
+### Arithmetic operators
+
 - `(eo::add t1 t2)`
-    - If `t1` and `t2` are arithmetic values of the same category, then this returns the addition of `t1` and `t2`.
-    - If `t1` and `t2` are bitwise values of the same category and bitwidth, this returns the binary value corresponding to their (unsigned) addition modulo their bitwidth.
+  - If `t1` and `t2` are arithmetic values of the same category, then this returns the addition of `t1` and `t2`.
+  - If `t1` and `t2` are bitwise values of the same category and bitwidth, this returns the binary value corresponding to their (unsigned) addition modulo their bitwidth.
 - `(eo::mul t1 t2)`
-    - If `t1` and `t2` are arithmetic values of the same category, then this returns the multiplication of `t1` and `t2`.
-    - If `t1` and `t2` are bitwise values of the same category and bitwidth, this returns the binary value corresponding to their (unsigned) multiplication modulo their bitwidth.
+  - If `t1` and `t2` are arithmetic values of the same category, then this returns the multiplication of `t1` and `t2`.
+  - If `t1` and `t2` are bitwise values of the same category and bitwidth, this returns the binary value corresponding to their (unsigned) multiplication modulo their bitwidth.
 - `(eo::neg t1)`
-    - If `t1` is a arithmetic value, this returns the arithmetic negation of `t1`.
-    - If `t1` is a binary value, this returns its (signed) arithmetic negation.
+  - If `t1` is a arithmetic value, this returns the arithmetic negation of `t1`.
+  - If `t1` is a binary value, this returns its (signed) arithmetic negation.
 - `(eo::qdiv t1 t2)`
-    - If `t1` and `t2` are values of the same category and `t2` is non-zero, then this returns the rational division of `t1` and `t2`.
+  - If `t1` and `t2` are values of the same category and `t2` is non-zero, then this returns the rational division of `t1` and `t2`.
 - `(eo::zdiv t1 t2)`
-    - If `t1` and `t2` are numeral values and `t2` is non-zero, then this returns the integer division (floor) of `t1` and `t2`.
-    - If `t1` and `t2` are bitwise values of the same category and bitwidth, then this returns their (total, unsigned) division, where division by zero returns the max unsigned value.
+  - If `t1` and `t2` are numeral values and `t2` is non-zero, then this returns the integer division (floor) of `t1` and `t2`.
+  - If `t1` and `t2` are bitwise values of the same category and bitwidth, then this returns their (total, unsigned) division, where division by zero returns the max unsigned value.
 - `(eo::zmod t1 t2)`
-    - If `t1` and `t2` are numeral values and `t2` is non-zero, then this returns the integer remainder of `t1` and `t2`.
-    - If `t1` and `t2` are bitwise values of the same category and bitwidth, then this returns their (total, unsigned) remainder, where remainder by zero returns `t1`.
+  - If `t1` and `t2` are numeral values and `t2` is non-zero, then this returns the integer remainder of `t1` and `t2`.
+  - If `t1` and `t2` are bitwise values of the same category and bitwidth, then this returns their (total, unsigned) remainder, where remainder by zero returns `t1`.
 - `(eo::is_neg t1)`
-    - If `t1` is an arithmetic value, this returns `true` if `t1` is strictly negative and `false` otherwise. Otherwise, this operator is not evaluated.
+  - If `t1` is an arithmetic value, this returns `true` if `t1` is strictly negative and `false` otherwise. Otherwise, this operator is not evaluated.
 - `(eo::gt t1 t2)`
-    - Equivalent to `(eo::is_neg (eo::add (eo::neg t1) t2))`.
+  - Equivalent to `(eo::is_neg (eo::add (eo::neg t1) t2))`.
+
+### String operators
 
-String operators:
 - `(eo::len t1)`
-    - Binary length (bitwidth) if `t1` is a binary value.
-    - String length if `t1` is a string value.
+  - Binary length (bitwidth) if `t1` is a binary value.
+  - String length if `t1` is a string value.
 - `(eo::concat t1 t2)`
-    - The concatenation of bits if `t1` and `t2` are binary values.
-    - The concatenation of strings if `t1` and `t2` are string values.
+  - The concatenation of bits if `t1` and `t2` are binary values.
+  - The concatenation of strings if `t1` and `t2` are string values.
 - `(eo::extract t1 t2 t3)`
-    - If `t1` is a binary value and `t2` and `t3` are numeral values, this returns the binary value corresponding to the bits in `t1` from position `t2` through `t3` if `0<=t2`, or the empty binary value otherwise.
-    - If `t1` is a string value and `t2` and `t3` are numeral values, this returns the string value corresponding to the characters in `t1` from position `t2` through `t3` inclusive if `0<=t2`, or the empty string value otherwise.
+  - If `t1` is a binary value and `t2` and `t3` are numeral values, this returns the binary value corresponding to the bits in `t1` from position `t2` through `t3` if `0<=t2`, or the empty binary value otherwise.
+  - If `t1` is a string value and `t2` and `t3` are numeral values, this returns the string value corresponding to the characters in `t1` from position `t2` through `t3` inclusive if `0<=t2`, or the empty string value otherwise.
 - `(eo::find t1 t2)`
-    - If `t1` and `t2` are string values, this returns a numeral value corresponding to the first index (left to right) where `t2` occurs as a substring of `t1`, or the numeral value `-1` otherwise.
-    
-Conversion operators:
+  - If `t1` and `t2` are string values, this returns a numeral value corresponding to the first index (left to right) where `t2` occurs as a substring of `t1`, or the numeral value `-1` otherwise.
+
+### Conversion operators
+
 - `(eo::to_z t1)`
-    - If `t1` is a numeral value, return `t1`.
-    - If `t1` is a rational value, return the numeral value corresponding to the floor of `t1`.
-    - If `t1` is a binary value, this returns the numeral value corresponding to `t1`.
-    - If `t1` is a string value of length one, this returns the code point of its character.
+  - If `t1` is a numeral value, return `t1`.
+  - If `t1` is a rational value, return the numeral value corresponding to the floor of `t1`.
+  - If `t1` is a binary value, this returns the numeral value corresponding to `t1`.
+  - If `t1` is a string value of length one, this returns the code point of its character.
 - `(eo::to_q t1)`
-    - If `t1` is a rational value, return `t1`.
-    - If `t1` is a numeral value, this returns the (integral) rational value that is equivalent to `t1`.
+  - If `t1` is a rational value, return `t1`.
+  - If `t1` is a numeral value, this returns the (integral) rational value that is equivalent to `t1`.
 - `(eo::to_bin t1 t2)`
-    - If `t1` is a 32-bit numeral value and `t2` is a binary value, this returns a binary value whose value is `t2` and whose bitwidth is `t1`.
-    - If `t1` is a 32-bit numeral value and `t2` is a numeral value, return the binary value whose value is `t2` (modulo `2^t1`) and whose bitwidth is `t1`.
+  - If `t1` is a 32-bit numeral value and `t2` is a binary value, this returns a binary value whose value is `t2` and whose bitwidth is `t1`.
+  - If `t1` is a 32-bit numeral value and `t2` is a numeral value, return the binary value whose value is `t2` (modulo `2^t1`) and whose bitwidth is `t1`.
 - `(eo::to_str t1)`
-    - If `t1` is a string value, return `t1`.
-    - If `t1` is a numeral value specifying a code point from Unicode planes `0-2` (i.e. a numeral between `0` and `196607`), return the string of length one whose character has code point `t1`.
-    - If `t1` is a rational or binary value, return the string value corresponding to the result of printing `t1`. 
-    - If `t1` is a hexadecimal value, return the string value corresponding to the result of printing `t1`. This will use lowercase letters for digits greater than `9`.
-    - If `t1` is a decimal value, return the string value corresponding to the result of printing `t1` as a rational.
+  - If `t1` is a string value, return `t1`.
+  - If `t1` is a numeral value specifying a code point from Unicode planes `0-2` (i.e. a numeral between `0` and `196607`), return the string of length one whose character has code point `t1`.
+  - If `t1` is a rational or binary value, return the string value corresponding to the result of printing `t1`. 
+  - If `t1` is a hexadecimal value, return the string value corresponding to the result of printing `t1`. This will use lowercase letters for digits greater than `9`.
+  - If `t1` is a decimal value, return the string value corresponding to the result of printing `t1` as a rational.
 
 The Ethos eagerly evaluates ground applications of computational operators.
 In other words, the term `(eo::add 1 1)` is syntactically equivalent in all contexts to `2`.
@@ -644,7 +712,7 @@ The Ethos supports extensions of `eo::and, eo::or, eo::xor, eo::add, eo::mul, eo
 
 ### Computation Examples
 
-```
+```smt
 (eo::and true false)        == false
 (eo::and #b1110 #b0110)     == #b0110
 (eo::or true false)         == true
@@ -657,10 +725,12 @@ The Ethos supports extensions of `eo::and, eo::or, eo::xor, eo::add, eo::mul, eo
 (eo::add 1/2 1/3)           == 5/6
 (eo::add 2 1/3)             == (eo::add 2 1/3)  ; no mixed arithmetic
 (eo::add 2/1 1/3)           == 7/3
-(eo::add 2.0 1/3)           == (eo::add 2.0 1/3)  ; since no mixed arithmetic
-(eo::add 2.0 2.5)           == 4.5
+(eo::add 2.0 1/3)           == 7/3  ; with default options
+(eo::add 2.0 1/3)           == (eo::add 2.0 1/3)  ; if --no-normalize-dec is enabled, since no mixed arithmetic
+(eo::add 2.0 2.5)           == 4.5  ; which is not syntactically equal to 9/2 if --no-normalize-dec is enabled
 (eo::add #b01 #b01)         == #b10
-(eo::add #x1 #b0001)        == (eo::add #x1 #b0001)  ; since no mixed arithmetic
+(eo::add #x1 #b0001)        == #b0002  ; with default options
+(eo::add #x1 #b0001)        == (eo::add #x1 #b0001)  ; if --no-normalize-hex is enabled
 (eo::mul 2 7)               == 14
 (eo::mul 2 2 7)             == 28
 (eo::mul 1/2 1/4)           == 1/8
@@ -668,7 +738,7 @@ The Ethos supports extensions of `eo::and, eo::or, eo::xor, eo::add, eo::mul, eo
 (eo::qdiv 12 6)             == 3/1
 (eo::qdiv 7 2)              == 7/2
 (eo::qdiv 7/1 2/1)          == 7/2
-(eo::qdiv 7.0 2.0)          == 7/2
+(eo::qdiv 7.0 2.0)          == 7/2  ; regardless of whether --no-normalize-dec is enabled
 (eo::qdiv 7 0)              == (eo::qdiv 7 0)  ; no division by zero
 (eo::zdiv 12 3)             == 4
 (eo::zdiv 7 2)              == 3
@@ -714,7 +784,7 @@ The Ethos supports extensions of `eo::and, eo::or, eo::xor, eo::add, eo::mul, eo
 
 Note the following examples of core operators for the given signature
 
-```
+```smt
 (declare-type Int ())
 (declare-const x Int)
 (declare-const y Int)
@@ -738,33 +808,36 @@ Note the following examples of core operators for the given signature
 In the above, it is important to note that `eo::is_eq` is a check for syntactic equality after evaluation.
 It does not require that its arguments denote values, so for example `(eo::is_eq x y)` returns `false`.
 
-## <a name="list-computation"></a> List computations
+<a name="list-computation"></a>
+
+## List computations
 
 Below, we assume that `f` is right associative operator with nil terminator `nil` and `t1, t2` are ground. Otherwise, the following operators do not evaluate.
 We describe the evaluation for right associative operators; left associative evaluation is defined analogously.
 We say that a term is an `f`-list with children `t1 ... tn` if it is of the form `(f t1 ... tn)` where `n>0` or `nil` if `n=0`.
 
-List operators:
+### List operators
+
 - `(eo::nil f)`
-    - If `f` is a right associative operator, return its nil terminator.
+  - If `f` is a right associative operator, return its nil terminator.
 - `(eo::cons f t1 t2)`
-    - If `t2` is an `f`-list, then this returns the term `(f t1 t2)`.
+  - If `t2` is an `f`-list, then this returns the term `(f t1 t2)`.
 - `(eo::list_len f t)`
-    - If `t` is an `f`-list with children `t1 ... tn`, then this returns `n`.
+  - If `t` is an `f`-list with children `t1 ... tn`, then this returns `n`.
 - `(eo::list_concat f t1 t2)`
-    - If `t1` is an `f`-list with children `t11 ... t1n` and `t2` is an `f`-list with children `t21 ... t2m`, this returns `(f t11 ... t1n t21 ... t2m)` if `n+m>0` and `nil` otherwise. Otherwise, this operator does not evaluate.
+  - If `t1` is an `f`-list with children `t11 ... t1n` and `t2` is an `f`-list with children `t21 ... t2m`, this returns `(f t11 ... t1n t21 ... t2m)` if `n+m>0` and `nil` otherwise. Otherwise, this operator does not evaluate.
 - `(eo::list_nth f t1 t2)`
-    - If `f` is a right associative operator with nil terminator with nil terminator `nil`, `t1` is `(f s0 ... s{n-1})`, and `t2` is a numeral value such that `0<=t2<n`, then this returns `s_{t2}`. Otherwise, this operator does not evaluate.
+  - If `f` is a right associative operator with nil terminator with nil terminator `nil`, `t1` is `(f s0 ... s{n-1})`, and `t2` is a numeral value such that `0<=t2<n`, then this returns `s_{t2}`. Otherwise, this operator does not evaluate.
 - `(eo::list_find f t1 t2)`
-    - If `f` is a right associative operator with nil terminator with nil terminator `nil` and `t1` is `(f s0 ... s{n-1})`, then this returns the smallest numeral value `i` such that `t2` is syntactically equal to `si`, or `-1` if no such `si` can be found. Otherwise, this operator does not evaluate.
+  - If `f` is a right associative operator with nil terminator with nil terminator `nil` and `t1` is `(f s0 ... s{n-1})`, then this returns the smallest numeral value `i` such that `t2` is syntactically equal to `si`, or `-1` if no such `si` can be found. Otherwise, this operator does not evaluate.
 
 ### List Computation Examples
 
 The terms on both sides of the given evaluation are written in their form prior to desugaring, where recall that e.g. `(or a)` after desugaring is `(or a false)` and `(or a b)` is `(or a (or b false))`.
 
-```
-(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
-(declare-const and (-> Bool Bool Bool) :right-assoc-nil true)
+```smt
+(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
+(declare-const and (->Bool Bool Bool) :right-assoc-nil true)
 (declare-const a Bool)
 (declare-const b Bool)
 
@@ -814,9 +887,9 @@ As we will introduce in [param-constants](#param-constants),
 In particular, `(eo::nil or a b)` intuitively denotes the nil terminator
 for the term `or` applied to arguments `a,b`.
 
-### Example: Type rule for BitVector concatentation
+### Example: Type rule for BitVector concatenation
 
-```
+```smt
 (declare-type Int ())
 (declare-consts <numeral> Int)
 (declare-type BitVec (Int))
@@ -838,7 +911,8 @@ Then, a type rule is given for bitvector concatenation `concat`, involves the re
 
 Since `eo::add` only evaluates on numeral values, this means that this type rule will only give the intended result when the bitwidth arguments to this function are concrete.
 If on the other hand we defined:
-```
+
+```smt
 ...
 (declare-const a Int)
 (declare-const b Int)
@@ -846,14 +920,17 @@ If on the other hand we defined:
 (declare-const y2 (BitVec b))
 (define z2 () (concat x2 y2) :type (BitVec (eo::add a b)))
 ```
+
 Based on the definition of `concat`, the return type of `z2` in the above example is `(BitVec (eo::add a b))`, where the application of `eo::add` does not evaluate since `a` and `b` are not values.
 However, any term with a type that is both ground (i.e. containing no parameters) and evaluatable (i.e. containing an application of a program or builtin evaluation operator) is considered ill-typed by Ethos.
 Hence, the above example results in a type checking error.
 This was not the case with `z` in the previous example, whose type prior to evaluation was`(BitVec (eo::add 2 3))`, which evaluates to `(BitVec 5)` which is a legal type.
 
-### <a name="bv-literals"></a>Example: Type rule for BitVector constants
+<a name="bv-literals"></a>
 
-```
+### Example: Type rule for BitVector constants
+
+```smt
 (declare-type Int ())
 (declare-consts <numeral> Int)
 (declare-type BitVec (Int))
@@ -862,45 +939,52 @@ This was not the case with `z` in the previous example, whose type prior to eval
 
 (define x () #b000 :type (BitVec 3))
 ```
+
 To define the class of binary values, whose type depends on the number of bits they contain, the Ethos provides support for a distinguished parameter `eo::self`.
 The type checker for values applies the substitution mapping `eo::self` to the term being type checked.
 This means that when type checking the binary constant `#b0000`, its type prior to evaluation is `(BitVec (eo::len #b0000))`, which evaluates to `(BitVec 4)`.
 
-## <a name="param-constants"></a>Parameterized constants
+<a name="param-constants"></a>
+
+## Parameterized constants
 
 Recall that in [assoc-nil](#assoc-nil), when using `declare-const` to define associative operators with nil terminators, it is not possible to have the nil terminator for that operator depend on its type parameters.
 In this section, we introduce a new command `declare-parameterized-const` which overcomes this limitation.
 Its syntax is:
-```
-(declare-parameterized-const <symbol> (<typed-param>*) <type> <attr>*)
+
+```smt
+(declare-parameterized-const <symbol> (<typed-param>*) <type> > <attr>*)
 ```
 
 In the following example,
 we declare bitvector-or (`bvor` in SMT-LIB) where its nil terminator is bitvector zero for the given bitwidth.
-```
+
+```smt
 (declare-type Int ())
-(declare-consts <numeral> Int)                ; numeral literals denote Int constants
+(declare-consts <numeral>Int)                ; numeral literals denote Int constants
 (declare-type BitVec (Int))
-(declare-consts <binary> 
+(declare-consts <binary>
     (BitVec (eo::len eo::self)))              ; binary literals denote BitVec constants of their length
 (define bvzero ((m Int)) (eo::to_bin m 0))    ; returns the bitvector value zero for bitwidth m
 
 (declare-parameterized-const bvor ((m Int))   ; bvor is parameterized by a bitwidth m
-    (-> (BitVec m) (BitVec m) (BitVec m))
+    (->(BitVec m) (BitVec m) (BitVec m))
     :right-assoc-nil (bvzero m)               ; its nil terminator depends on m
 )
 ```
+
 In this example, we first declare the `Int` and `BitVec` sorts, and associate numeral and binary values with those sorts (see [declare-consts](#declare-consts)).
 Then, we declare `bvor` using `declare-parameterized-const` where its parameter is an integer `m`.
 The provided parameters are in scope for the remainder of the command, which means they can appear in the nil terminator of the operator.
 Here, we specify `(bvzero m)` as the nil terminator for `bvor`.
 
-The parameter list of a parameterized constant are treated as *implicit* arguments.
-In this example, the type of `bvor` is `(-> (! Int :var m :implicit) (BitVec m) (BitVec m) (BitVec m))`.
+The parameter list of a parameterized constant are treated as _implicit_ arguments.
+In this example, the type of `bvor` is `(->(! Int :var m :implicit) (BitVec m) (BitVec m) (BitVec m))`.
 
 If a function `f` is given a nil terminator with free parameters, this impacts:
-- How applications of `f` are desugared, and
-- How list operations such as `eo::nil`, `eo::cons`, and `eo::list_concat` are computed for `f`.
+
+- how applications of `f` are desugared, and
+- how list operations such as `eo::nil`, `eo::cons`, and `eo::list_concat` are computed for `f`.
 
 For the former, say we apply `(f t1 ... tn)`, where `f` is right associative with nil terminator `nil`, where `nil` has free paramters `u1 ... um`.
 Similar to the procedure described in [assoc-nil](#assoc-nil), if `tn` is not marked with `:list`, we insert the nil terminator of `f` to the end of the argument list.
@@ -912,8 +996,9 @@ In other words, the computation of the nil terminator is deferred to this term (
 Otherwise, the nil terminator is `nil[ v1 ... vm / u1 ... um]`.
 Constructing `(f t1 ... tn)` then proceeds inductively via the same procedure described in [assoc-nil](#assoc-nil).
 Examples of this are given in the following, assuming the declaration of `bvor` above.
-```
-(declare-const p (-> Bool Bool))
+
+```smt
+(declare-const p (->Bool Bool))
 (define test ((x (BitVec 4)) (y (BitVec 4)) (n Int) (z (BitVec n)) (w (BitVec n)) (u (BitVec n) :list))
     ...
     (bvor x y)        ; (bvor x (bvor y #b0000))
@@ -924,13 +1009,14 @@ Examples of this are given in the following, assuming the declaration of `bvor`
     ...
 )
 ```
+
 Above, notice that `x` and `y` have concrete bitwidths and `z,w,u` have the free parameter `n` as their bitwidth.
 In the first term, `(bvor x y)` is type checked to `(BitVec m)[4/m]`.
 Since `4` is ground, we compute the nil terminator `(bvzero 4)`, which evaluates to `#b0000`.
 This is then used as the nil terminator, since `y` is not marked with `:list`.
 The second example is similar.
 
-In the third, example, `(bvor z w)` is type checked to `(BitVec m)[n/m]`, where note that `n` is *not* ground.
+In the third, example, `(bvor z w)` is type checked to `(BitVec m)[n/m]`, where note that `n` is _not_ ground.
 Thus, we do not compute its nil terminator and instead construct the placeholder `(eo::nil bvor z w)`.
 This is then used as the nil terminator since `w` is not marked as `:list`.
 In the fourth example, `(bvor z u)` is also type checked to `(BitVec m)[n/m]`, but in this case the nil terminator is not used since `u` is marked as `:list`.
@@ -943,7 +1029,8 @@ If we do not infer a ground nil terminator, then the term does not evaluate.
 Examples can be found at the end of this section.
 
 Consider again the term `(bvor z w)` from the previous example:
-```
+
+```smt
 (define test ((n Int) (z (BitVec n)) (w (BitVec n)))
     (bvor z w)        ; (bvor z (bvor w (eo::nil bvor z w)))
 )
@@ -951,19 +1038,21 @@ Consider again the term `(bvor z w)` from the previous example:
 (declare-const b (BitVec 4))
 (define test4 () (test 4 a b))
 ```
+
 The term in the body of `test` desugars to `(bvor z (bvor w (eo::nil bvor z w)))`, where
 `(eo::nil bvor z w)` does not evaluate since the nil terminator of `(bvor z w)` involves a non-ground parameter `n`.
 In this example, we instantiate this definition in the body of `test4`, where `n=4`, `z=a` and `w=b`.
 The term `(bvor a (bvor b (eo::nil bvor a b)))` then evaluates to `(bvor a (bvor b #b0000)`, since the nil terminator of `(bvor a b)` has ground parameter `n=4` and evaluates to `#b0000`.
 
-> Alternatively, the parameters of a function `f` may be provided explicitly using the syntax `(eo::_ f p1 ... pn)`.
+> __Note:__ Alternatively, the parameters of a function `f` may be provided explicitly using the syntax `(eo::_ f p1 ... pn)`.
 When parameters are provided, these are used instead of the type inference method above.
 Furthermore, these parameters are dropped when applying the operator to arguments.
 For example `(_ (eo::_ bvor 4) a b)` is equivalent to `(bvor a (bvor b #b0000))` after desugaring.
 An example use case for this feature is directly refer to the nil terminator of a concrete instance of `bvor`, e.g. `(eo::nil (eo::_ bvor 4))` evaluates to `#b0000`.
 
 The following are examples of list operations when using parameterized constant `bvor`:
-```
+
+```smt
 (declare-const a (BitVec 4))
 (declare-const b (BitVec 4))
 (declare-const c (BitVec 5))
@@ -981,53 +1070,61 @@ The following are examples of list operations when using parameterized constant
 (eo::list_concat bvor (bvor a b) (bvor b)) == (bvor a b b)
 ```
 
-> If no free parameters are used in the nil terminator of a parameterized constant, then it is treated equivalent to if it were declared via an ordinary declare-const command, and a warning is issued.
+> __Note:__ If no free parameters are used in the nil terminator of a parameterized constant, then it is treated equivalent to if it were declared via an ordinary declare-const command, and a warning is issued.
+
+<a name="overloading"></a>
 
-## <a name="overloading"></a>Overloading
+## Overloading
 
 The Ethos supports symbol overloading.
 For example, the following is accepted:
-```
+
+```smt
 (declare-const - (-> Int Int))
 (declare-const - (-> Int Int Int))
 (declare-const - (-> Real Real Real))
 ```
+
 When parsing a term whose head is `-`, the Ethos will automatically choose which symbol to use based on the arguments passed to it.
 In particular, if a symbol is overloaded, the Ethos will use the first symbol that results in a well-typed term if applied.
-For example, ssuming standard definitions of SMT-LIB literal values,
+For example, assuming standard definitions of SMT-LIB literal values,
 `(- 1)` uses the first, `(- 0 1)` uses the second, and `(- 0.0 1.0)` uses the third.
 If a symbol is unapplied, then the Ethos will interpret it as the first declared term for that symbol.
 
-> When multiple variants are possible, the Ethos will use the first one and will *not* throw a warning. This behavior permits the user to order the declarations in the order of their precedence. For example, the SMT-LIB operator for unary negation should be declared *before* the declaration for subtraction. If this were done in the opposite order, then (- t) would be interpreted as the partial application of subtraction to the term t.
+> __Note:__ When multiple variants are possible, the Ethos will use the first one and will _not_ throw a warning. This behavior permits the user to order the declarations in the order of their precedence. For example, the SMT-LIB operator for unary negation should be declared _before_ the declaration for subtraction. If this were done in the opposite order, then (- t) would be interpreted as the partial application of subtraction to the term t.
 
-Furthermore, the Ethos supports an operator `eo::as` for disambiguation whose syntax is `(eo::as <term> <type>)`.
-A term of the form `(eo::as t (-> T1 ... Tn T))` evaluates to term `s` only if `(s k1 ... kn)` has type `T` where `k1 ... kn` are variables of type `T1 ... Tn`, and `t` and `s` are atomic terms with the same name.
+Furthermore, the Ethos supports an operator `eo::as` for disambiguation whose syntax is `(eo::as <term><type>)`.
+A term of the form `(eo::as t (->T1 ... Tn T))` evaluates to term `s` only if `(s k1 ... kn)` has type `T` where `k1 ... kn` are variables of type `T1 ... Tn`, and `t` and `s` are atomic terms with the same name.
 If multiple such terms `s` exist, then the most recent one is returned.
-Otherwise, the term `(eo::as t (-> T1 ... Tn T))` is unevaluated.
+Otherwise, the term `(eo::as t (->T1 ... Tn T))` is unevaluated.
 For example, `(eo::as - (-> Int Int Int))` evaluates to the second declared symbol in the example above.
 
-# Declaring Proof Rules
+## Declaring Proof Rules
 
 The generic syntax for a `declare-rule` command accepted by `ethos` is:
-```
+
+```smt
 (declare-rule <symbol> <keyword>? <sexpr>*)
 ```
+
 When parsing this command, `ethos` will determine the format of the expected arguments based on the given keyword.
 If the `<keyword>` is not provided, the we assume it has been marked `:ethos`.
 All rules not marked with `:ethos` are not supported by the checker are unsupported and will cause the checker to terminate.
 
 If the keyword is `:ethos`, then the expected syntax that follows is given below:
-```
+
+```smt
 (declare-rule <symbol> :ethos (<typed-param>*) <assumption>? <premises>? <arguments>? <reqs>? :conclusion <term> <attr>*)
 where
-<assumption>    ::= :assumption <term>
-<premises>      ::= :premises (<term>*) | :premise-list <term> <term>
-<arguments>     ::= :args (<term>*)
-<reqs>          ::= :requires ((<term> <term>)*)
+<assumption>   ::= :assumption <term>
+<premises>     ::= :premises (<term>*) | :premise-list <term><term>
+<arguments>    ::= :args (<term>*)
+<reqs>         ::= :requires ((<term><term>)*)
 ```
 
 A proof rule begins by defining a list of free parameters, followed by 4 optional fields and a conclusion term.
 These fields include:
+
 - `<premises>`, denoting the premise patterns of the proof rule. This is either a list of formulas (via `:premises`) or the specification of list of premises via (via `:premise-list`), which will be described in detail later.
 - `<arguments>`, denoting argument patterns of provide to a proof rule.
 - `<reqs>`, denoting a list of pairs of terms.
@@ -1040,19 +1137,20 @@ This in turn impacts the response of the Ethos, as described in [responses](#res
 
 At a high level, an application of a proof rule is given a concrete list of (premise) proofs, and a concrete list of (argument) terms.
 A proof rule checks if a substitution `S` can be found such that:
+
 - The formulas proven by the premise proofs match provided premise patterns under substitution `S`,
 - The argument terms match the provided argument patterns under substitution `S`,
-- The requirements are *satisfied* under substitution `S`, namely, each pair of terms in the requirements list evaluates pairwise to the same term.
+- The requirements are _satisfied_ under substitution `S`, namely, each pair of terms in the requirements list evaluates pairwise to the same term.
 If these criteria are met, then the proof rule proves the result of applying `S` to the conclusion term.
 
 A proof rule is only well defined if the free parameters of the requirements and conclusion term are also contained in the arguments and premises.
 
-> Internally, proofs can be seen as terms whose type is given by a distinguished `Proof` type. In particular, `Proof` is a type whose kind is `(-> Bool Type)`, where the argument of this type is the formula that is proven. For example, `(Proof (> x 0))` is the proof that `x` is greater than zero. By design, the user cannot declare terms involving type `Proof`. Instead, proofs can only be constructed via the commands `assume` and `step` as we describe in [proofs](#proofs).
+> __Note:__ Internally, proofs can be seen as terms whose type is given by a distinguished `Proof` type. In particular, `Proof` is a type whose kind is `(->Bool Type)`, where the argument of this type is the formula that is proven. For example, `(Proof (> x 0))` is the proof that `x` is greater than zero. By design, the user cannot declare terms involving type `Proof`. Instead, proofs can only be constructed via the commands `assume` and `step` as we describe in [proofs](#proofs).
 
 ### Example rule: Reflexivity of equality
 
-```
-(declare-const = (-> (! Type :var T :implicit) T T Bool))
+```smt
+(declare-const = (->(! Type :var T :implicit) T T Bool))
 (declare-rule refl ((T Type) (t T))
     :premises ()
     :args (t)
@@ -1067,8 +1165,8 @@ Notice that the type `T` is a part of the parameter list and not explicitly prov
 
 ### Example rule: Symmetry of Equality
 
-```
-(declare-const = (-> (! Type :var T :implicit) T T Bool))
+```smt
+(declare-const = (->(! Type :var T :implicit) T T Bool))
 (declare-rule symm ((T Type) (t T) (s T))
     :premises ((= t s))
     :conclusion (= s t)
@@ -1076,13 +1174,13 @@ Notice that the type `T` is a part of the parameter list and not explicitly prov
 ```
 
 This rule specifies symmetry of equality. This rule takes as premise an equality `(= t s)` and no arguments.
-In detail, an application of this proof rule for premise proof `(= a b)` for concrete terms `a,b` will compute the substitution `{ t -> a, s -> b }` and apply it to the conclusion term to obtain `(= b a)`.
+In detail, an application of this proof rule for premise proof `(= a b)` for concrete terms `a,b` will compute the substitution `{ t ->a, s ->b }` and apply it to the conclusion term to obtain `(= b a)`.
 
-## Requirements
+### Requirements
 
 A list of requirements can be given to a proof rule.
 
-```
+```smt
 (declare-type Int ())
 (declare-consts <numeral> Int)
 (declare-const >= (-> Int Int Bool))
@@ -1095,16 +1193,17 @@ A list of requirements can be given to a proof rule.
 This rule expects an arithmetic inequality.
 It requires that the left hand side of this inequality `x` is a negative numeral, which is checked via the requirement `:requires (((eo::is_neg x) true))`.
 
-## Premise lists
+### Premise lists
 
-A rule can take an arbitrary number of premises via the syntax `:premise-list <term> <term>`. For example:
+A rule can take an arbitrary number of premises via the syntax `:premise-list <term><term>`. For example:
 
-```
-(declare-const and (-> Bool Bool Bool) :right-assoc-nil true)
+```smt
+(declare-const and (->Bool Bool Bool) :right-assoc-nil true)
 (declare-rule and-intro ((F Bool))
     :premise-list F and
     :conclusion F)
 ```
+
 This syntax specifies that the number of premises that are provided to this rule are arbitrary.
 When applying this rule, the formulas proven to this rule (say `F1 ... Fn`) will be collected and constructed as a single formula via the provided operator (`and`), and subsequently matched against the premise pattern `F`.
 In particular, in this case `F` is bound to `(and F1 ... Fn)`.
@@ -1112,20 +1211,24 @@ The conclusion of the rule returns `F` itself.
 
 Note that the type of functions provided as the second argument of `:premise-list` should be operators that are marked to take an arbitrary number of arguments, that is those marked e.g. with `:right-assoc-nil` or `:chainable`.
 
-#  <a name="proofs"></a> Writing Proofs
+<a name="proofs"></a>
 
-The Eunoia language provies the commands `assume` and `step` for defining proofs. Their syntax is given by:
-```
+## Writing Proofs
+
+The Eunoia language provides the commands `assume` and `step` for defining proofs. Their syntax is given by:
+
+```smt
 (assume <symbol> <term>)
 (step <symbol> <term>? :rule <symbol> <premises>? <arguments>?)
 where
-<premises>      ::= :premises (<term>*)
-<arguments>     ::= :args (<term>*)
+<premises>     ::= :premises (<term>*)
+<arguments>    ::= :args (<term>*)
 ```
+
 ### Example proof: symmetry of equality
 
-```
-(declare-const = (-> (! Type :var T :implicit) T T Bool))
+```smt
+(declare-const = (->(! Type :var T :implicit) T T Bool))
 (declare-rule symm ((T Type) (t T) (s T))
     :premises ((= t s))
     :conclusion (= s t)
@@ -1143,8 +1246,8 @@ The Eunoia language includes commands `assume-push` and `step-pop` with the same
 However, the former can be seen as introducing a local assumption that is consumed by the latter.
 We give an example of this in following.
 
-```
-(declare-const => (-> Bool Bool Bool))
+```smt
+(declare-const => (->Bool Bool Bool))
 (declare-rule implies-intro ((F Bool) (G Bool))
   :assumption F
   :premises (G)
@@ -1169,7 +1272,8 @@ The command `step-pop` then consumes the proof of `@p1` and binds `@p3` to a pro
 Notice that `@p1` is removed from scope after `@p3` is applied.
 
 Locally assumptions can be arbitrarily nested, for example the above can be extended to:
-```
+
+```smt
 ...
 (assume-push @p0 true)
 (assume-push @p1 false)
@@ -1178,12 +1282,14 @@ Locally assumptions can be arbitrarily nested, for example the above can be exte
 (step-pop @p4 (=> true (=> false true)) :rule implies-intro :premises (@p3))
 ```
 
-# Side Conditions
+## Side Conditions
 
 Similar to `declare-rule`, the Ethos supports an extensible syntax for programs whose generic syntax is given by:
+
+```smt
+(program <symbol> > <keyword>? <sexpr>*)
 ```
-(program <symbol> <keyword>? <sexpr>*)
-```
+
 When parsing this command, `ethos` will determine the format of the expected arguments based on the given keyword.
 If the `<keyword>` is not provided, the we assume it has been marked `:ethos`.
 All programs not marked with `:ethos` are not supported by the checker are unsupported and will cause the checker to terminate.
@@ -1191,31 +1297,34 @@ All programs not marked with `:ethos` are not supported by the checker are unsup
 If the keyword is `:ethos`, then the expected syntax that follows is given below, and is used for defining recursive programs.
 In particular, in the Ethos, a program is an ordered lists of rewrite rules.
 The syntax for this command is as follows.
-```
+
+```smt
 (program <symbol> :ethos (<typed-param>*) (<type>*) <type> ((<term> <term>)+))
 ```
+
 This command declares a program named `<symbol>`.
 The provided type parameters are implicit and are used to define its type signature and body.
 
 The type of the program is given immediately after the parameter list, provided as a list of argument types and a return type.
-The semantics of the program is given by a non-empty list of pairs of terms, which we call its *body*.
+The semantics of the program is given by a non-empty list of pairs of terms, which we call its _body_.
 For program `f`, This list is expected to be a list of terms of the form `(((f t11 ... t1n) r1) ... ((f tm1 ... tmn) rm))`
 where `t11...t1n, ..., tm1...tmn` do not contain computational operators.
 A (ground) term `(f s1 ... sn)` evaluates by finding the first term in the first position of a pair of this list that matches it for substitution `S`, and returns the result of applying `S` to the right hand side of that pair.
 If no such term can be found, then the application does not evaluate.
 
-> Terms in program bodies are not statically type checked. Evaluating a program may introduce non-well-typed terms if the program body is malformed.
+> __Note:__ Terms in program bodies are not statically type checked. Evaluating a program may introduce non-well-typed terms if the program body is malformed.
 
-> For each case `((f ti1 ... tin) ri)` in the program body, the free parameters in `ri` are required to be a subset of the free parameters in `(f ti1 ... tin)`. Otherwise, an error is thrown.
+> __Note:__ For each case `((f ti1 ... tin) ri)` in the program body, the free parameters in `ri` are required to be a subset of the free parameters in `(f ti1 ... tin)`. Otherwise, an error is thrown.
 
-> If a case is provided `(si ri)` in the definition of program `f` where `si` is not an application of `f`, an error is thrown.
+> __Note:__ If a case is provided `(si ri)` in the definition of program `f` where `si` is not an application of `f`, an error is thrown.
 Furthermore, if `si` contains any computational operators (i.e. those with `eo::` prefix), then an error is thrown.
 
 ### Example: Finding a child in an `or` term
 
 The following program (recursively) computes whether a formula `l` is contained as the direct child of an application of `or`:
-```
-(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
+
+```smt
+(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
 (program contains
     ((l Bool) (x Bool) (xs Bool :list))
     (Bool Bool) Bool
@@ -1228,7 +1337,7 @@ The following program (recursively) computes whether a formula `l` is contained
 ```
 
 First, we declare the parameters `l, x, xs`, each of type `Bool`.
-These parameters are used for defining the body of the program, but do *not* necessarily coincide with the expected arguments to the program.
+These parameters are used for defining the body of the program, but do _not_ necessarily coincide with the expected arguments to the program.
 We then declare the type of the program `(Bool Bool) Bool`, i.e. the type of `contains` is a function expecting two Booleans and returning a Boolean.
 The body of the program is then given in three cases.
 First, terms of the form `(contains false l)` evaluate to `false`, that is, we failed to find `l` in the second argument.
@@ -1238,13 +1347,14 @@ Otherwise, terms of the form `(contains (or x xs) l)` evaluate in one step to `(
 In this example, since `xs` was marked with `:list`, the terms `(or l xs)` and `(or x xs)` are desugared to terms where `xs` is matched with the tail of the input.
 The next two examples show variants where an incorrect definition of this program is defined.
 
-> As mentioned in [list-computation](#list-computation), Eunoia has dedicated support for operators over lists.
+> __Note:__ As mentioned in [list-computation](#list-computation), Eunoia has dedicated support for operators over lists.
 For the definition of `contains` in the above example, the term `(contains l c)` is equivalent to `(eo::not (eo::is_neg (eo::find or c l)))`.
 Computing the latter is significantly faster in practice in the Ethos.
 
 ### Example: Finding a child in an `or` term (incorrect version)
-```
-(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
+
+```smt
+(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
 (program contains
     ((l Bool) (x Bool) (xs Bool))
     (Bool Bool) Bool
@@ -1258,12 +1368,13 @@ Computing the latter is significantly faster in practice in the Ethos.
 
 In this variant, `xs` was not marked with `:list`.
 Thus, `(or l xs)` and `(or x xs)` are desugared to `(or l (or xs false))` and `(or x (or xs false))` respectively.
-In other words, these terms will match `or` terms with *exactly* two children, for example `(contains (or a b) a)` will still evaluate to `true`.
+In other words, these terms will match `or` terms with _exactly_ two children, for example `(contains (or a b) a)` will still evaluate to `true`.
 However, `(contains (or a b c) a)` does not evaluate in this example.
 
 ### Example: Finding a child in an `or` term (incorrect version 2)
-```
-(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
+
+```smt
+(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
 (program contains
     ((l Bool) (x Bool :list) (xs Bool :list))
     (Bool Bool) Bool
@@ -1274,16 +1385,17 @@ However, `(contains (or a b c) a)` does not evaluate in this example.
     )
 )
 ```
+
 In this variant, both `xs` and `x` were marked with `:list`.
 The Ethos will reject this definition since it implies that a computational operator appears in a pattern for matching.
 In particular, the term `(or x xs)` is equivalent to `(eo::list_concat or x xs)` after desugaring.
 Thus, the third case of the program, `(contains (eo::list_concat or x xs) l)`, is not a legal pattern.
 
-### <a name="ex-substitution"></a>Example: Substitution
+### Example: Substitution
 
-```
+```smt
 (program substitute
-  ((T Type) (U Type) (S Type) (x S) (y S) (f (-> T U)) (a T) (z U))
+  ((T Type) (U Type) (S Type) (x S) (y S) (f (->T U)) (a T) (z U))
   (S S U) U
   (
   ((substitute x y x)     y)
@@ -1299,32 +1411,12 @@ In detail, recall that the Ethos treats all function applications as curried (un
 In particular, this implies that `(f a)` matches any application term, since both `f` and `a` are parameters.
 Thus, the side condition is written in three cases: either `t` is `x` in which case we return `y`, `t` is a function application in which case we recurse, or otherwise `t` is a constant not equal to `x` and we return itself.
 
-This method will not replace subterms inside of opaque arguments (see [opaque](#opaque)).
-In particular, a term such as `(@array_diff A B)` will remain unchanged for a substitution e.g. replacing `A` with `B`, since `(@array_diff A B)` is not a function application.
-Hence when `t` is `(@array_diff A B)`, we fall into the third case of the method above for any call to `substitute` where `x` is not `(@array_diff A B)` itself.
-
-Alternatively, the following version of substitution `substitute-o` pattern matches on applications of `@array_diff` explicitly.
-Calling it with arguments `A`, `B`, and `(@array_diff A B)` would return `(@array_diff B B)`.
-
-```
-(program substitute-o
-  ((T Type) (U Type) (S Type) (x S) (y S) (a (Array T U)) (b (Array T U)) (z U))
-  (S S U) U
-  (
-  ((substitute-o x y x)                 y)
-  ((substitute-o x y (f a))             (_ (substitute-o x y f) (substitute-o x y a)))
-  ((substitute-o x y (@array_diff a b)) (@array_diff (substitute-o x y a) (substitute-o x y b)))
-  ((substitute-o x y z)                 z)
-  )
-)
-```
-
 ### Example: Term evaluator
 
-```
+```smt
 (declare-type Int ())
 (declare-consts <numeral> Int)
-(declare-const = (-> (! Type :var T :implicit) T T Bool))
+(declare-const = (->(! Type :var T :implicit) T T Bool))
 (declare-const + (-> Int Int Int))
 (declare-const - (-> Int Int Int))
 (declare-const < (-> Int Int Bool))
@@ -1343,11 +1435,12 @@ Calling it with arguments `A`, `B`, and `(@array_diff A B)` would return `(@arra
     )
 )
 ```
+
 The above example recursively evaluates arithmetic terms and predicates according to their intended semantics.
 
 ### Example: A computational type rule
 
-```
+```smt
 (declare-type Int ())
 (declare-type Real ())
 (program arith.typeunion ()
@@ -1359,7 +1452,7 @@ The above example recursively evaluates arithmetic terms and predicates accordin
       ((arith.typeunion Real Real) Real)
     )
 )
-(declare-const + (-> (! Type :var T :implicit)
+(declare-const + (->(! Type :var T :implicit)
                      (! Type :var U :implicit)
                      T U (arith.typeunion T U)))
 ```
@@ -1370,12 +1463,12 @@ The return type of `+` invokes this side condition, which conceptually is implem
 
 ### Example: Conversion to DIMACS
 
-```
+```smt
 (declare-type String ())
 (declare-consts <string> String)
-(declare-const not (-> Bool Bool))
-(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
-(declare-const and (-> Bool Bool Bool) :right-assoc-nil true)
+(declare-const not (->Bool Bool))
+(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
+(declare-const and (->Bool Bool Bool) :right-assoc-nil true)
 
 (program to_drat_lit ((l Bool))
   (Bool) Int
@@ -1400,25 +1493,28 @@ The return type of `+` invokes this side condition, which conceptually is implem
   )
 )
 ```
+
 The above program `to_dimacs` converts an SMT formula into DIMACS form, where `eo::hash` is used to assign atoms to integer identifiers.
 
-## Match statements in Eunoia
+### Match statements
 
 The Ethos supports an operator `eo::match` for performing pattern matching on a target term. The syntax of this term is:
-```
+
+```smt
 (eo::match (<typed-param>*) <term> ((<term> <term>)*))
 ```
+
 The term `(eo::match (...) t ((s1 r1) ... (sn rn)))` finds the first term `si` in the list `s1 ... sn` that `t` can be matched with under some substitution and returns the result of applying that substitution to `ri`.
 
-> Match terms require the free parameters of `ri` are a subset of the provided parameter list.
+> __Note:__  Match terms require the free parameters of `ri` are a subset of the provided parameter list.
 In other words, all patterns must only involve parameters that are locally bound as the first argument of the match term.
 Also, similar to programs, the free parameters of `ri` that occur in the parameter list must be a subset of `si`, or else an error is thrown.
 
-> Like programs, match terms are not statically type checked.
+> __Note:__ Like programs, match terms are not statically type checked.
 
 ### Examples of legal and illegal match terms
 
-```
+```smt
 (declare-type Int ())
 (declare-const F Bool)
 (declare-const a Int)
@@ -1456,13 +1552,12 @@ Also, similar to programs, the free parameters of `ri` that occur in the paramet
         )))  
 ```
 
-
 ### Example: Proof rule for symmetry of (dis)equality
 
-```
+```smt
 (declare-type Int ())
-(declare-const = (-> (! Type :var T :implicit) T T Bool))
-(declare-const not (-> Bool Bool))
+(declare-const = (->(! Type :var T :implicit) T T Bool))
+(declare-const not (->Bool Bool))
 (declare-rule symm ((F Bool))
     :premises (F)
     :conclusion
@@ -1474,14 +1569,16 @@ Also, similar to programs, the free parameters of `ri` that occur in the paramet
         )
 )
 ```
+
 The above rule performs symmetry on equality or disequality.
 It matches the given premise `F` with either `(= t1 t2)` or `(not (= t1 t2))` and flips the terms on the sides of the (dis)equality.
 
 Internally, the semantics of `eo::match` can be seen as an (inlined) program applied to its head, such that the above example is equivalent to:
-```
+
+```smt
 (declare-type Int ())
-(declare-const = (-> (! Type :var T :implicit) T T Bool))
-(declare-const not (-> Bool Bool))
+(declare-const = (->(! Type :var T :implicit) T T Bool))
+(declare-const not (->Bool Bool))
 (program matchF ((t1 Int) (t2 Int))
     (Bool) Bool
     (
@@ -1496,15 +1593,15 @@ Internally, the semantics of `eo::match` can be seen as an (inlined) program app
 )
 ```
 
-> The Ethos automatically performs the above transformation on match terms for consistency.
+> __Note:__ The Ethos automatically performs the above transformation on match terms for consistency.
 In more general cases, if the body of the match term contains free variables, these are added to the argument list of the internally generated program.
 
 ### Example: Proof rule for transitivity of equality with a premise list
 
-```
+```smt
 (declare-type Int ())
-(declare-const = (-> (! Type :var T :implicit) T T Bool))
-(declare-const and (-> Bool Bool Bool) :left-assoc)
+(declare-const = (->(! Type :var T :implicit) T T Bool))
+(declare-const and (->Bool Bool Bool) :left-assoc)
 
 (program mk_trans ((t1 Int) (t2 Int) (t3 Int) (t4 Int) (tail Bool :list))
     (Int Int Bool) Bool
@@ -1525,43 +1622,45 @@ In more general cases, if the body of the match term contains free variables, th
 ```
 
 For simplicity, the rule is given only for equalities of the integer sort, although this rule can be generalized.
-The proof rule `trans` first packages an arbtirary number of premises, constructs a conjunction of these premises, which to bound to `E` and passed to the match term in the conclusion.
+The proof rule `trans` first packages an arbitrary number of premises, constructs a conjunction of these premises, which to bound to `E` and passed to the match term in the conclusion.
 The recursive calls in the side condition `mk_trans` accumulate the endpoints of an equality chain and ensure via `eo::requires` that further equalities extend the left hand side of this chain.
 
-# Including and referencing files
+## Including and referencing files
 
 The Ethos supports the following commands for file inclusion:
+
 - `(include <string>)`, which includes the file indicated by the given string. The path to the file is taken relative to the directory of the file that includes it.
-- `(reference <string> <symbol>?)`, which similar to `include` includes the file indicated by the given string, and furthermore marks that file as being the *reference input* for the current run of the checker (see below). The optional symbol can refer to a normalization routine (see below).
+- `(reference <string> <symbol>?)`, which similar to `include` includes the file indicated by the given string, and furthermore marks that file as being the _reference input_ for the current run of the checker (see below). The optional symbol can refer to a normalization routine (see below).
 
-## Validation Proofs via Reference Inputs
+### Validation Proofs via Reference Inputs
 
-When the Ethos encounters a command of the form `(reference <string>)`, the checker enables a further set of checks that ensures that all assumptions in proofs correspond to assertions from the file referenced by the given string.
+When the Ethos encounters a command of the form `(reference <string>)`, the checker enables a further set of checks that ensures that all assumptions in proofs correspond to assertions from the reference file.
 
 In particular, when the command `(reference "file.smt2")` is read, the Ethos will parse `file.smt2`.
 The definitions and declaration commands in this file will be treated as normal, that is, they will populate the symbol table of the Ethos as they normally would if they were to appear in an `*.eo` input.
-The commands of the form `(assert F)` will add `F` to a set of formulas we will refer to as the *reference assertions*.
+The commands of the form `(assert F)` will add `F` to a set of formulas we will refer to as the _reference assertions_.
 Other commands in `file.smt2` (e.g. `set-logic`, `set-option`, and so on) will be ignored.
 
 If ethos has read a reference file, then for each command of the form `(assume <symbol> G)`, ethos will check whether `G` occurs in the set of parsed reference assertions.
 If it does not, then an error is thrown indicating that the proof is assuming a formula that is not a part of the original input.
 
-> Only one reference command can be executed for each run of ethos.
+> __Note:__ Only one reference command can be executed for each run of ethos.
 
-> Incremental `*.smt2` inputs are not supported as reference files in the current version of ethos.
+> __Note:__ Incremental `*.smt2` inputs are not supported as reference files in the current version of ethos.
 
-## Validation up to Normalization
+### Validation up to Normalization
 
 Since the validation is relying on the fact that ethos can faithfully parse the original *.smt2 file, validation will only succeed if the signatures used by the Ethos exactly match the syntax for terms in the *.smt2 file.
 Minor changes in how terms are represented will lead to mismatches.
 For this reason, ethos additionally supports providing an optional normalization routine via `(reference <string> <term>)`, which includes the file indicated by the given string and specifies all assumptions must match an assertion after running the provided normalization function.
 
 For example:
-```
+
+```smt
 (declare-type Int ())
 (declare-type Real ())
 (declare-const / (-> Int Int Real))
-(program normalize ((T Type) (S Type) (f (-> S T)) (x S) (a Int) (b Int))
+(program normalize ((T Type) (S Type) (f (->S T)) (x S) (a Int) (b Int))
    (T) T
    (
      ((normalize (/ a b)) (eo::qdiv a b))
@@ -1571,18 +1670,19 @@ For example:
 )
 (reference "file.smt2" normalize)
 ```
+
 Here, `normalize` is introduced as a program which recursively replaces all occurrences of division (over integer constants) with the resulting rational constant.
 This method can be used for handling solvers that interpret constant division as the construction of a rational constant.
 The above program will be invoked on all formulas occuring in `assert` commands in `"file.smt2"` and subsequently formulas in `assume` commands.
 
-# Oracles
+## Oracles
 
 The Ethos supports a command, `declare-oracle-fun`, which associates the semantics of a function with an external binary.
-We reference to such functions as *oracle functions*.
+We reference to such functions as _oracle functions_.
 The syntax and semantics of such functions are described in this [paper](https://homepage.divms.uiowa.edu/~ajreynol/vmcai22a.pdf).
 
 In particular, the Ethos supports the command:
-```
+```smt
 (declare-oracle-fun <symbol> (<type>*) <type> <symbol>)
 ```
 Like the `declare-fun` command from SMT-LIB, this command declares a constant named `<symbol>` whose type is given by the argument types and return type.
@@ -1591,10 +1691,10 @@ Ground applications of oracle functions are eagerly evaluated by invoking the bi
 
 ### Example: Oracle isPrime
 
-```
+```smt
 (declare-type Int ())
 (declare-consts <numeral> Int)
-(declare-const = (-> (! Type :var T :implicit) T T Bool))
+(declare-const = (->(! Type :var T :implicit) T T Bool))
 (declare-const >= (-> Int Int Bool))
 
 (declare-oracle-fun runIsPrime (Int) Bool ./isPrime)
@@ -1617,21 +1717,29 @@ The user is responsible that the input can be properly parsed by the oracle, and
 
 In the above example, a proof rule is then defined that says that if `z` is an integer greater than or equal to `2`, is the product of two integers `x` and `y`, and is prime based on invoking `runIsPrime` in the given requirement, then we can conclude `false`.
 
-# <a name="responses"></a> Checker Response
+<a name="responses"></a>
+
+## Checker Response
 
 After successfully parsing an input file with no errors, the Ethos will respond with one of two possibilities:
+
 - `incomplete` if it parsed any `step` or `step-pop` application that referenced a proof rule that was marked with the attribute `:sorry`, or
 - `correct` otherwise.
 
-Note however that the Ethos does not impose any requirements on *what* was proven in the proof.
+Note however that the Ethos does not impose any requirements on _what_ was proven in the proof.
 The user is responsible for ensure that e.g. the proof contains a step with a desired conclusion (e.g. `false`).
 
-# Appendix
+## Appendix
 
-## Command line options of ethos
+### Command line options of ethos
 
 The Ethos command line interface can be invoked by `ethos <option>* <file>` where `<option>` is one of the following:
+
+- `--binder-fresh`: binders generate fresh variables when parsed in proof files.
 - `--help`: displays a help message.
+- `--no-normalize-dec`: do not treat decimal literals as syntax sugar for rational literals.
+- `--no-normalize-hex`: do not treat hexadecimal literals as syntax sugar for binary literals.
+- `--no-parse-let`: do not treat `let` as a builtin symbol for specifying terms having shared subterms.
 - `--no-print-let`: do not letify the output of terms in error messages and trace messages.
 - `--no-rule-sym-table`: do not use a separate symbol table for proof rules and declared terms.
 - `--show-config`: displays the build information for the given binary.
@@ -1640,29 +1748,11 @@ The Ethos command line interface can be invoked by `ethos <option>* <file>` wher
 - `-t <tag>`: enables the given trace tag (for debugging).
 - `-v`: verbose mode, enable all standard trace messages.
 
-The following options impact how proof files and reference files are parsed only (for details on classifications of files, see [full-syntax](#full-syntax). 
-They do not impact how signature files (*.eo) are parsed:
-- `--binder-fresh`: binders generate fresh variables.
-- `--normalize-num`: treat numeral literals as syntax sugar for (integral) rational literals.
-- `--no-normalize-dec`: do not treat decimal literals as syntax sugar for rational literals.
-- `--no-normalize-hex`: do not treat hexadecimal literals as syntax sugar for binary literals.
-- `--no-parse-let`: do not treat `let` as a builtin symbol for specifying a macro.
-
-## <a name="full-syntax"></a> Full syntax for Eunoia commands
-
-Below defines the syntax accepted by the Ethos parser.
+### Full syntax for Eunoia commands
 
-We distinguish three kinds of file inputs:
-- *Proof files* are files that are given via command line option that do *not* have extension `*.eo`.
-Their expected syntax is `<eo-command>*`.
-- *Reference files* are files included via the `reference` command.
-Their expected syntax is `<smtlib2-command>*`.
-- *Signature files* are files that given via command line option that have extension `*.eo`, or those that are included via the command `include`.
+Valid inputs to the Ethos are `<eo-command>*`, where:
 
-As mentioned, the first two kinds of file inputs take into account options concerning the normalization of terms (e.g. `--normalize-num`), while signature files do not.
-When streaming input to Ethos, we assume the input is being given for a proof file.
-
-```
+```smt
 ;;;
 <eo-command> ::=
     (assume <symbol> <term>) |
@@ -1728,12 +1818,16 @@ When streaming input to Ethos, we assume the input is being given for a proof fi
 
 ```
 
-### <a name="non-core-eval"></a>Definitions of Non-Core Evaluation Operators
+Moreover, a valid input for a file included by the Eunoia command `<reference>` is `<smtlib2-command>*`;
+a valid input for a file included by the Eunoia command `<include>` is `<eo-command>*`.
 
-The following signature can be used to define operators that are not required to be supported as core evaluation operators.
+ <a name="non-core-eval"></a>
 
-```
+### Definitions of Non-Core Evaluation Operators
+
+The following signature can be used to define operators that are not required to be supported as core evaluation operators.
 
+```smt
 ; Returns true if x is a numeral literal.
 (define eo::is_z ((T Type :implicit) (x T))
   (eo::is_eq (eo::to_z x) x))
@@ -1765,45 +1859,47 @@ The following signature can be used to define operators that are not required to
 
 ; An arbitrary deterministic comparison of terms. Returns true if a > b based
 ; on this ordering.
-(define eo::cmp ((T Type :implicit) (U Type :implicit) (a T) (b U))
+(define eo::com ((T Type :implicit) (U Type :implicit) (a T) (b U))
   (eo::is_neg (eo::add (eo::hash b) (eo::neg (eo::hash a)))))
 
 ```
 
-## Proofs as terms
+### Proofs as terms
 
 This section overviews the semantics of proofs in the Eunoia language.
 Proof checking can be seen as a special instance of type checking terms involving the `Proof` and `Quote` types.
 The type system of the Ethos can be summarized as follows, where `t : S` are assumed axioms for all atomic terms `t` of type `S`:
 
-```
-f : (-> (Quote u) S)  t : T
+```smt
+f : (->(Quote u) S)  t : T
 ---------------------------- if u * sigma = t
 (f t) : S * sigma
 
 
-f : (-> U S)  t : T
+f : (->U S)  t : T
 ------------------- if U * sigma = T
 (f t) : S * sigma
 
 for all other (non-Quote) types U.
-
 ```
 
 Note that Ethos additionally requires that all well-typed terms have a type that is either non-ground, or is fully reduced, i.e. contains no irreducible applications of programs or evaluation operators.
 
 The command:
-```
+
+```smt
 (declare-rule s ((v1 T1) ... (vi Ti)) 
     :premises (p1 ... pn) 
     :args (t1 ... tm) 
     :requires ((r1 s1) ... (rk sk)) 
     :conclusion t)
 ```
+
 can be seen as syntax sugar for:
-```
+
+```smt
 (declare-const s
-    (-> (! T1 :var v1 :implicit) ... (! Ti :var vi :implicit)
+    (->(! T1 :var v1 :implicit) ... (! Ti :var vi :implicit)
         (Proof p1) ... (Proof pn)
         (Quote t1) ... (Quote tm)
         (eo::requires r1 s1 ... (eo::requires rk sk
@@ -1811,21 +1907,28 @@ can be seen as syntax sugar for:
 ```
 
 The command:
-```
+
+```smt
 (assume s f)
 ```
+
 can be seen as syntax sugar for:
-```
+
+```smt
 (declare-const s (Proof f))
 ```
 
 The command:
-```
+
+```smt
 (step s f :rule r :premises (p1 ... pn) :args (t1 ... tm))
 ```
+
 can be seen as syntax sugar for:
-```
+
+```smt
 (define s () (r p1 ... pn t1 ... tm) :type (Proof f))
 ```
+
 If no conlusion is provided, then the type attribute is not specified.
 Notice this is only the case if the declaration of `r` does not involve `:assumption` or `:premise-list`.

From 986c2e32314a9ed1293700fac68c9e3a6e37886f Mon Sep 17 00:00:00 2001
From: Cesare Tinelli <cesare-tinelli@uiowa.edu>
Date: Sun, 1 Sep 2024 19:07:27 -0500
Subject: [PATCH 02/12] Minor fixes

---
 .gitignore     |   2 +-
 user_manual.md | 151 +++++++++++++++++++++++++------------------------
 2 files changed, 77 insertions(+), 76 deletions(-)

diff --git a/.gitignore b/.gitignore
index 18996606..5acb669b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,2 @@
 build
-.vscode
\ No newline at end of file
+.vscode
diff --git a/user_manual.md b/user_manual.md
index 44d745c2..e9bfbce9 100644
--- a/user_manual.md
+++ b/user_manual.md
@@ -81,10 +81,8 @@ In the following sections, we describe these features in more detail. A full syn
 In Eunoia, as in SMT-LIB version 3.0, a common BNF is used to specify _terms_ (expressions denoting values), _types_ (expressions denoting sets of values) and _kinds_ (expressions denoting sets of types).
 In this document, unless specified otherwise, we will use _term_ more generally to refer to a value term, a type, or a kind
 Terms are composed of applications, built-in operators of the language (e.g., for performing computations, see [computation](#computation)), literals (see [literals](#literals)), and three kinds of atomic terms (_constants_, _variables_, and _parameters_) which we describe in the following.
-A _function (symbol)_ is an atomic term having a function type, that is, a type of the form `(->... ...)`.
-The standard `let` binder can be used for specifying terms that contain common subterms,
-which is treated as syntax sugar.
-<!--CT This is to be discussed further since I am not clear that it is really treated as syntactic sugar. -->
+A _function (symbol)_ is an atomic term having a function type, that is, a type of the form `(-> ... ...)`.
+The builtin `eo::define` binder can be used for specifying terms that contain common subterms analogously to `let` binders in other languages.
 
 The core language of Eunoia does not have any builtin SMT-LIB theories.
 Instead, SMT-LIB theories may defined as Eunoia signatures.
@@ -111,7 +109,7 @@ The following commands are supported for declaring and defining types and terms.
   <!-- Added-->
   This is a derived command as it is a shorthand for
   `(declare-const <symbol> Type)` if `<type>*` is empty, and for
-  `(declare-const <symbol> (-><type>* Type))` otherwise.
+  `(declare-const <symbol> (-> <type>* Type))` otherwise.
 
 <!--CT Do we really need `define-type`? -->
 - `(define-type <symbol> (<type>*) <type>)` defines `<symbol>` to be a lambda term whose type is given by the argument and return types.
@@ -129,7 +127,7 @@ The Eunoia language contains further commands for declaring symbols that are not
 
 - `(declare-parameterized-const <symbol> (<typed-param>*) <type> <attr>*)` declares a globally scoped variable named `<symbol>` whose type is `<type>`.
 
-> __Note:__ Variables are internally treated the same as constants by Ethos. However, but are provided as a separate category, e.g., for user signatures that wish to distinguish universally quantified variables from free constants. They also have a relationship with user-defined binders, see [binders](#binders), and can be accessed via the builtin operator `eo::var` (see [computation](#computation)).
+> __Note:__ Variables are internally treated the same as constants by Ethos. However, they are provided as a separate category, e.g., for user signatures that wish to distinguish universally quantified variables from free constants. They also have a relationship with user-defined binders, see [binders](#binders), and can be accessed via the builtin operator `eo::var` (see [computation](#computation)).
 
 > __Note:__ Symbol overloading is supported, see [overloading](#overloading).
 
@@ -143,7 +141,7 @@ The Eunoia language contains further commands for declaring symbols that are not
 (declare-const P (-> Int Bool))
 ```
 
-Since Ethos does not assume any builtin definitions of SMT-LIB theories, definitions of standard symbols (such as `Int`) may be provided in Eunoia signatures<!--CT How are they provided? And aren't integers builtin? -->. In the above example, symbol `c` is declared to be a constant (0-ary) symbol of type `Int`. The symbol `f` is a function taking two integers and returning an integer.
+Since Ethos does not assume any builtin definitions of SMT-LIB theories, definitions of standard symbols (such as `Int`) may be provided in Eunoia signatures<!--CT I bet this point is going to be confusing to users. -->. In the above example, symbol `c` is declared to be a constant (0-ary) symbol of type `Int`. The symbol `f` is a function taking two integers and returning an integer.
 
 Observe that despite using different syntax in their declarations, the types of `f` and `g` in the above example are identical as `->` is a right-associative binary type constructor.
 
@@ -152,7 +150,7 @@ Observe that despite using different syntax in their declarations, the types of
 #### Example: Basic Definitions
 
 ```smt
-(declare-const not (->Bool Bool))
+(declare-const not (-> Bool Bool))
 (define id ((x Bool)) x)
 (define notId ((x Int)) (not (id x)))
 ```
@@ -163,9 +161,8 @@ Since `define` commands are treated as (hygienic) macro definitions, in this exa
 Furthermore, `notId` is mapped to the lambda term `(lambda ((x Bool)) (not x))`.
 In other words, the following sequence of commands is equivalent to the one above after parsing:
 
-<!--CT This is literally identical to the previous list of commands -->
 ```smt
-(declare-const not (->Bool Bool))
+(declare-const not (-> Bool Bool))
 (define id ((x Bool)) x)
 (define notId ((x Int)) (not x))
 ```
@@ -183,7 +180,7 @@ Eunoia supports the declaration of polymorphic types, that is, types depending o
 (declare-const b (IntArray Bool))
 ```
 
-In the above example, we declare and integer type constructor of kind `Type` and array type constructor of kind is `(->Type Type Type)`.
+In the above example, we declare and integer type constructor of kind `Type` and array type constructor of kind is `(-> Type Type Type)`.
 
 <!-- We should say something about the defines above -->
 
@@ -191,7 +188,7 @@ Note the following declarations generate terms of the same type:
 
 ```smt
 (declare-type Array_v2 (Type Type))
-(declare-const Array_v3 (->Type Type Type))
+(declare-const Array_v3 (-> Type Type Type))
 ```
 
 <a name="literals"></a>
@@ -203,7 +200,7 @@ To type check terms, `define` statements can be annotated with `:type <term>`.
 In particular:
 
 ```smt
-(declare-const not (->Bool Bool))
+(declare-const not (-> Bool Bool))
 (define notTrue () (not true) :type Bool)
 ```
 
@@ -215,7 +212,7 @@ The Eunoia language uses the SMT-LIB version 3.0 attributes `:var <symbol>` and
 
 ```smt
 (declare-type Int ())
-(declare-const eq (->(! Type :var T) T T Bool))
+(declare-const eq (-> (! Type :var T) T T Bool))
 (define P ((x Int) (y Int)) (eq Int x y))
 ```
 
@@ -225,7 +222,7 @@ In contrast, the example below declares a predicate `=` where the type of the ar
 
 ```smt
 (declare-type Int ())
-(declare-const = (->(! Type :var T :implicit) T T Bool))
+(declare-const = (-> (! Type :var T :implicit) T T Bool))
 (define P ((x Int) (y Int)) (= x y))
 ```
 
@@ -236,10 +233,10 @@ We call `T` in the above definitions a _parameter_. The free parameters of the r
 
 ```smt
 (declare-type Int ())
-(declare-const f (->(! Type :var T :implicit) Int T))
+(declare-const f (-> (! Type :var T :implicit) Int T))
 ```
 
-> __Note:__ Internally, `(! T :var t)` is syntax sugar for the type `(Quote t)` where `t` is a parameter of type `T` and `Quote` is a distinguished type of kind `(->(! Type :var U) U Type)`. When type checking applications of functions of type `(->(Quote t) S)`, the parameter `t` is bound to the argument the function is applied to.
+> __Note:__ Internally, `(! T :var t)` is syntax sugar for the type `(Quote t)` where `t` is a parameter of type `T` and `Quote` is a distinguished type of kind `(-> (! Type :var U) U Type)`. When type checking applications of functions of type `(-> (Quote t) S)`, the parameter `t` is bound to the argument the function is applied to.
 
 > __Note:__ Internally, `(! T :implicit)` drops `T` from the list of arguments of the function type we are defining.
 
@@ -249,7 +246,7 @@ Arguments to functions can also be annotated with the attribute `:requires (<ter
 
 ```smt
 (declare-type Int ())
-(declare-const BitVec (->(! Int :var w :requires ((eo::is_neg w) false)) Type))
+(declare-const BitVec (-> (! Int :var w :requires ((eo::is_neg w) false)) Type))
 ```
 The above declares the integer type `Int` and a bitvector type constructor `BitVec` that expects a _non-negative integer_ `w`.
 In detail, the first argument of `BitVec` is supposed to be an `Int` value and is named `w` via the `:var` attribute.
@@ -258,7 +255,7 @@ Symbol `eo::is_neg` denotes a builtin function that returns `true` if its argume
 <!-- This needs discussion, what is the input type of `eo::is_neg`? How can `eo::is_neg` accept a value of a user-defined type `Int` given that it is builtin?  -->
 
 > __Note:__ Internally, `(! T :requires (t s))` is syntax sugar for the type term `(eo::requires t s T)` where `eo::requires` is an operator that evaluates to its third argument if and only if its first two arguments are _computationally_ equivalent (details on this operator are given in [computation](#computation))<!--CT This is non-ideal from a language design point of view as it makes the semantic of Eunoia non-compositional: the meaning of `eo::requires` applications changes depending on whether there are in positive or negative positions. -->.
-Furthermore, the function type `(->(eo::requires t s T) S)` is treated as `(->T (eo::requires t s S))`. Ethos rewrites all types of the former form to the latter.
+Furthermore, the function type `(-> (eo::requires t s T) S)` is treated as `(-> T (eo::requires t s S))`. Ethos rewrites all types of the former form to the latter.
 
 <a name="attributes"></a>
 
@@ -268,7 +265,7 @@ The Eunoia language supports term annotations on declared constants, which for i
 
 - `:right-assoc` (resp. `:left-assoc`) denoting that application of the declared binary constant to more than two terms are to be treated as right (resp. left) associative,
 
-- `:right-assoc-nil <symbol>` (resp. `:left-assoc-nil <symbol>`) denoting that applications of the declared binary constant to one or more terms are to be treated as right (resp. left) associative, with the given `<symbol>` used as an additional rightmost (resp. leftmost) argument.
+- `:right-assoc-nil <term>` (resp. `:left-assoc-nil <term>`) denoting that applications of the declared binary constant to one or more terms are to be treated as right (resp. left) associative, with the given `<term>` used as an additional rightmost (resp. leftmost) argument.
 <!--CT Do we really want to restrict the nil element to be a symbol, as opposed to a term? -->
 
 - `:chainable <symbol>` denoting that the arguments of the declared binary constant are chainable using the (binary) operator given by `<symbol>`,
@@ -286,7 +283,7 @@ A parameter in a function symbol declaration may be marked with the following at
 #### Right/Left associative
 
 ```smt
-(declare-const or (->Bool Bool Bool) :right-assoc)
+(declare-const or (-> Bool Bool Bool) :right-assoc)
 (define P ((x Bool) (y Bool) (z Bool)) (or x y z))
 (define Q ((x Bool) (y Bool)) (or x y))
 (define R ((x Bool)) (or x))
@@ -294,18 +291,19 @@ A parameter in a function symbol declaration may be marked with the following at
 
 In the above example, `(or x y z)` is treated as `(or x (or y z))`.
 The term `(or x y)` is not impacted by the annotation `:right-assoc` since it has fewer than 3 children.
-The term `(or x)` is also not impacted by the annotation, and denotes the _partial application_ of `or` to `x`, whose type is `(->Bool Bool)`.
+The term `(or x)` is also not impacted by the annotation, and denotes the _partial application_ of `or` to `x`, whose type is `(-> Bool Bool)`.
 
 Left associative can be defined analogously:
 
 ```smt
-(declare-const and (->Bool Bool Bool) :left-assoc)
+(declare-const and (-> Bool Bool Bool) :left-assoc)
 (define P ((x Bool) (y Bool) (z Bool)) (and x y z))
 ```
 
 In the above example, `(and x y z)` is treated as `(and (and x y) z)`.
 
-Note that the type for right and left associative operators is typically `(->T T T)` for some type `T`. <!--CT Added. Is this the case in Ethos? -->More generally, a constant declared with the `:right-associative` annotation must have a type of the form `(->T1 T2 T2)` for some types `T1` and `T2`. Similarly, a constant declared with the `:left-associative` annotation must have a type of the form `(->T1 T2 T1)`.
+Note that the type for right and left associative operators is typically `(-> T T T)` for some type `T`.
+More generally, a constant declared with the `:right-associative` annotation must have a type of the form `(-> T1 T2 T2)` for some types `T1` and `T2`. Similarly, a constant declared with the `:left-associative` annotation must have a type of the form `(-> T1 T2 T1)`.
 
 <a name="assoc-nil"></a>
 
@@ -314,7 +312,7 @@ Note that the type for right and left associative operators is typically `(->T T
 Eunoia supports a variant of the aforementioned functionality where a (ground) nil terminator is provided.
 
 ```smt
-(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
+(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
 (define P ((x Bool) (y Bool) (z Bool)) (or x y z))
 (define Q ((x Bool) (y Bool)) (or x y))
 (define R ((x Bool) (y Bool)) (or x))
@@ -332,12 +330,15 @@ The advantage of right or left associative operators with nil terminators is tha
 In particular, note the following example:
 
 ```smt
-(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
+(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
 (define P ((x Bool) (y Bool) (z Bool)) (or x (or y z)))
 (define Q ((x Bool) (y Bool) (z Bool)) (or x y z))
 ```
 
-<!--CT I do not think this is a cogent example since `(or x (or y z)))` and `(or x (or y z)))` are semantically equivalent anyway given that `false` is a neutral element for `or`. The difference would be clearer with a nil element that was not also a neutral element. 
+<!--CT We should stress that we get to different AST for the P and Q above.
+-->
+
+ <!--CT We should point out that the nil element should be a left and right identity of the assoc symbol, otherwise non-intuitive results occur. 
 
 For instance, with
 (declare-const + (-> Int Int Int) :right-assoc-nil 1)
@@ -353,7 +354,7 @@ In contrast, marking `or` with `:right-assoc-nil false` leads to the distinct te
 
 Right and left associative operators with nil terminators also have a relationship with list terms (as we will see in the following section), and in computational operators.
 
-The type for right and left associative operators with nil terminators is typically `(->T T T)` for some `T`, where their nil terminator has type `T`. <!--CT Added. Is it the case in Ethos? -->More generally, a constant declared with the `:right-associative-nil` annotation must have a type of the form `(->T1 T2 T2)` where `T2` is the type of the nil constant, for some types `T1` and `T2`. Similarly, a constant declared with the `:left-associative` annotation must have a type of the form `(->T1 T2 T1)` where `T1` is the type of the nil constant.
+The type for right and left associative operators with nil terminators is typically `(-> T T T)` for some `T`, where their nil terminator has type `T`. <!--CT Added.--> More generally, a constant declared with the `:right-associative-nil` annotation must have a type of the form `(-> T1 T2 T2)` where `T2` is the type of the nil constant, for some types `T1` and `T2`. Similarly, a constant declared with the `:left-associative` annotation must have a type of the form `(-> T1 T2 T1)` where `T1` is the type of the nil constant.
 
 The nil terminator of a right associative operator may involve previously declared symbols in the signature.
 For example:
@@ -361,7 +362,7 @@ For example:
 ```smt
 (declare-type RegLan ())
 (declare-const re.all RegLan)
-(declare-const re.inter (->RegLan RegLan RegLan) :right-assoc-nil re.all)
+(declare-const re.inter (-> RegLan RegLan RegLan) :right-assoc-nil re.all)
 ```
 
 This example defines the constant `re.all` (in SMT-LIB, this is the regular expression generating the set of all strings)
@@ -374,7 +375,7 @@ A possible declaration is the following:
 
 ```smt
 (declare-const bvor
-    (->(! Int :var m :implicit) (BitVec m) (BitVec m) (BitVec m))
+    (-> (! Int :var m :implicit) (BitVec m) (BitVec m) (BitVec m))
     :right-assoc-nil ???
 )
 ```
@@ -389,7 +390,7 @@ Atomic terms can be marked with the annotation `:list`.<!--CT Do we really need
 This annotation marks that the term should be treated as a list of arguments when it occurs as an argument of a right (left) associative operator with a nil element. Note the following example:
 
 ```smt
-(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
+(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
 (define P ((x Bool) (y Bool)) (or x y))
 (define Q ((x Bool) (y Bool :list)) (or x y))
 (declare-const a Bool)
@@ -420,7 +421,7 @@ if `ti` is marked with `:list`.
 Examples of this desugaring are given below.
 
 ```smt
-(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
+(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
 (define test ((x Bool) (y Bool) (z Bool :list) (w Bool :list))
     (and
         (or x y)        ; (or x (or y false))
@@ -439,7 +440,7 @@ In contrast, `(or x)` denotes the `or` whose children are `x` and `false`.
 
 ```smt
 (declare-type Int ())
-(declare-const and (->Bool Bool Bool) :right-assoc)
+(declare-const and (-> Bool Bool Bool) :right-assoc)
 (declare-const >= (-> Int Int Bool) :chainable)
 (define ((x Int) (y Int) (z Int)) (>= x y z))
 (define Q ((x Int) (y Int)) (>= x y))
@@ -448,24 +449,24 @@ In contrast, `(or x)` denotes the `or` whose children are `x` and `false`.
 In the above example, `(>= x y z w)` is syntax sugar for `(and (>= x y) (>= y z))`,
 whereas the term `(>= x y)` is not impacted by the annotation `:chainable` since it has fewer than 3 children.
 
-Note that the type for chainable operators is typically `(->T T S)` for some types `T` and `S`,
-where the type of its chaining operator is `(->S S S)`, and that operator has been as variadic via some attribute (e.g. `:right-assoc`).
+Note that the type for chainable operators is typically `(-> T T S)` for some types `T` and `S`,
+where the type of its chaining operator is `(-> S S S)`, and that operator has been as variadic via some attribute (e.g. `:right-assoc`).
 
 #### Pairwise
 
 ```smt
 (declare-type Int ())
-(declare-const and (->Bool Bool Bool) :right-assoc)
-(declare-const distinct (->(! Type :var T :implicit) T T Bool)
+(declare-const and (-> Bool Bool Bool) :right-assoc)
+(declare-const distinct (-> (! Type :var T :implicit) T T Bool)
  :pairwise and)
 (define P ((x Int) (y Int) (z Int)) (distinct x y z))
 ```
 
 In the above example, `(distinct x y z)` is treated as `(and (distinct x y) (distinct x z) (distinct y z))`.
 
-Note that the type for chainable operators is typically `(->T T S)` for some types `T` and `S`,
-where the type of its pairwise operator is `(->S S S)`,
-and that operator has been as variadic via some attribute<!--CT I do not understand this sentence -->.
+Note that the type for pairwise operators is typically `(-> T T S)` for some types `T` and `S`,
+where the type of its pairwise operator is `(-> S S S)`<!--CT This could be generalized, right? -->,
+and that operator has been marked as variadic via some attribute.
 
 <a name="binders"></a>
 
@@ -477,9 +478,9 @@ and that operator has been as variadic via some attribute<!--CT I do not underst
 (declare-type Int ())
 (declare-type @List ())
 (declare-const @nil @List)
-(declare-const @cons (->(! Type :var T :implicit) T @List @List)
+(declare-const @cons (-> (! Type :var T :implicit) T @List @List)
  :right-assoc-nil @nil)
-(declare-const forall (->@List Bool Bool) :binder @cons)
+(declare-const forall (-> @List Bool Bool) :binder @cons)
 (declare-const P (-> Int Bool))
 
 (define Q1 () (forall ((x Int)) (P x)))
@@ -836,8 +837,8 @@ We say that a term is an `f`-list with children `t1 ... tn` if it is of the form
 The terms on both sides of the given evaluation are written in their form prior to desugaring, where recall that e.g. `(or a)` after desugaring is `(or a false)` and `(or a b)` is `(or a (or b false))`.
 
 ```smt
-(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
-(declare-const and (->Bool Bool Bool) :right-assoc-nil true)
+(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
+(declare-const and (-> Bool Bool Bool) :right-assoc-nil true)
 (declare-const a Bool)
 (declare-const b Bool)
 
@@ -968,7 +969,7 @@ we declare bitvector-or (`bvor` in SMT-LIB) where its nil terminator is bitvecto
 (define bvzero ((m Int)) (eo::to_bin m 0))    ; returns the bitvector value zero for bitwidth m
 
 (declare-parameterized-const bvor ((m Int))   ; bvor is parameterized by a bitwidth m
-    (->(BitVec m) (BitVec m) (BitVec m))
+    (-> (BitVec m) (BitVec m) (BitVec m))
     :right-assoc-nil (bvzero m)               ; its nil terminator depends on m
 )
 ```
@@ -979,7 +980,7 @@ The provided parameters are in scope for the remainder of the command, which mea
 Here, we specify `(bvzero m)` as the nil terminator for `bvor`.
 
 The parameter list of a parameterized constant are treated as _implicit_ arguments.
-In this example, the type of `bvor` is `(->(! Int :var m :implicit) (BitVec m) (BitVec m) (BitVec m))`.
+In this example, the type of `bvor` is `(-> (! Int :var m :implicit) (BitVec m) (BitVec m) (BitVec m))`.
 
 If a function `f` is given a nil terminator with free parameters, this impacts:
 
@@ -998,7 +999,7 @@ Constructing `(f t1 ... tn)` then proceeds inductively via the same procedure de
 Examples of this are given in the following, assuming the declaration of `bvor` above.
 
 ```smt
-(declare-const p (->Bool Bool))
+(declare-const p (-> Bool Bool))
 (define test ((x (BitVec 4)) (y (BitVec 4)) (n Int) (z (BitVec n)) (w (BitVec n)) (u (BitVec n) :list))
     ...
     (bvor x y)        ; (bvor x (bvor y #b0000))
@@ -1094,9 +1095,9 @@ If a symbol is unapplied, then the Ethos will interpret it as the first declared
 > __Note:__ When multiple variants are possible, the Ethos will use the first one and will _not_ throw a warning. This behavior permits the user to order the declarations in the order of their precedence. For example, the SMT-LIB operator for unary negation should be declared _before_ the declaration for subtraction. If this were done in the opposite order, then (- t) would be interpreted as the partial application of subtraction to the term t.
 
 Furthermore, the Ethos supports an operator `eo::as` for disambiguation whose syntax is `(eo::as <term><type>)`.
-A term of the form `(eo::as t (->T1 ... Tn T))` evaluates to term `s` only if `(s k1 ... kn)` has type `T` where `k1 ... kn` are variables of type `T1 ... Tn`, and `t` and `s` are atomic terms with the same name.
+A term of the form `(eo::as t (-> T1 ... Tn T))` evaluates to term `s` only if `(s k1 ... kn)` has type `T` where `k1 ... kn` are variables of type `T1 ... Tn`, and `t` and `s` are atomic terms with the same name.
 If multiple such terms `s` exist, then the most recent one is returned.
-Otherwise, the term `(eo::as t (->T1 ... Tn T))` is unevaluated.
+Otherwise, the term `(eo::as t (-> T1 ... Tn T))` is unevaluated.
 For example, `(eo::as - (-> Int Int Int))` evaluates to the second declared symbol in the example above.
 
 ## Declaring Proof Rules
@@ -1145,12 +1146,12 @@ If these criteria are met, then the proof rule proves the result of applying `S`
 
 A proof rule is only well defined if the free parameters of the requirements and conclusion term are also contained in the arguments and premises.
 
-> __Note:__ Internally, proofs can be seen as terms whose type is given by a distinguished `Proof` type. In particular, `Proof` is a type whose kind is `(->Bool Type)`, where the argument of this type is the formula that is proven. For example, `(Proof (> x 0))` is the proof that `x` is greater than zero. By design, the user cannot declare terms involving type `Proof`. Instead, proofs can only be constructed via the commands `assume` and `step` as we describe in [proofs](#proofs).
+> __Note:__ Internally, proofs can be seen as terms whose type is given by a distinguished `Proof` type. In particular, `Proof` is a type whose kind is `(-> Bool Type)`, where the argument of this type is the formula that is proven. For example, `(Proof (> x 0))` is the proof that `x` is greater than zero. By design, the user cannot declare terms involving type `Proof`. Instead, proofs can only be constructed via the commands `assume` and `step` as we describe in [proofs](#proofs).
 
 ### Example rule: Reflexivity of equality
 
 ```smt
-(declare-const = (->(! Type :var T :implicit) T T Bool))
+(declare-const = (-> (! Type :var T :implicit) T T Bool))
 (declare-rule refl ((T Type) (t T))
     :premises ()
     :args (t)
@@ -1166,7 +1167,7 @@ Notice that the type `T` is a part of the parameter list and not explicitly prov
 ### Example rule: Symmetry of Equality
 
 ```smt
-(declare-const = (->(! Type :var T :implicit) T T Bool))
+(declare-const = (-> (! Type :var T :implicit) T T Bool))
 (declare-rule symm ((T Type) (t T) (s T))
     :premises ((= t s))
     :conclusion (= s t)
@@ -1198,7 +1199,7 @@ It requires that the left hand side of this inequality `x` is a negative numeral
 A rule can take an arbitrary number of premises via the syntax `:premise-list <term><term>`. For example:
 
 ```smt
-(declare-const and (->Bool Bool Bool) :right-assoc-nil true)
+(declare-const and (-> Bool Bool Bool) :right-assoc-nil true)
 (declare-rule and-intro ((F Bool))
     :premise-list F and
     :conclusion F)
@@ -1228,7 +1229,7 @@ where
 ### Example proof: symmetry of equality
 
 ```smt
-(declare-const = (->(! Type :var T :implicit) T T Bool))
+(declare-const = (-> (! Type :var T :implicit) T T Bool))
 (declare-rule symm ((T Type) (t T) (s T))
     :premises ((= t s))
     :conclusion (= s t)
@@ -1247,7 +1248,7 @@ However, the former can be seen as introducing a local assumption that is consum
 We give an example of this in following.
 
 ```smt
-(declare-const => (->Bool Bool Bool))
+(declare-const => (-> Bool Bool Bool))
 (declare-rule implies-intro ((F Bool) (G Bool))
   :assumption F
   :premises (G)
@@ -1324,7 +1325,7 @@ Furthermore, if `si` contains any computational operators (i.e. those with `eo::
 The following program (recursively) computes whether a formula `l` is contained as the direct child of an application of `or`:
 
 ```smt
-(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
+(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
 (program contains
     ((l Bool) (x Bool) (xs Bool :list))
     (Bool Bool) Bool
@@ -1354,7 +1355,7 @@ Computing the latter is significantly faster in practice in the Ethos.
 ### Example: Finding a child in an `or` term (incorrect version)
 
 ```smt
-(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
+(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
 (program contains
     ((l Bool) (x Bool) (xs Bool))
     (Bool Bool) Bool
@@ -1374,7 +1375,7 @@ However, `(contains (or a b c) a)` does not evaluate in this example.
 ### Example: Finding a child in an `or` term (incorrect version 2)
 
 ```smt
-(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
+(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
 (program contains
     ((l Bool) (x Bool :list) (xs Bool :list))
     (Bool Bool) Bool
@@ -1395,7 +1396,7 @@ Thus, the third case of the program, `(contains (eo::list_concat or x xs) l)`, i
 
 ```smt
 (program substitute
-  ((T Type) (U Type) (S Type) (x S) (y S) (f (->T U)) (a T) (z U))
+  ((T Type) (U Type) (S Type) (x S) (y S) (f (-> T U)) (a T) (z U))
   (S S U) U
   (
   ((substitute x y x)     y)
@@ -1416,7 +1417,7 @@ Thus, the side condition is written in three cases: either `t` is `x` in which c
 ```smt
 (declare-type Int ())
 (declare-consts <numeral> Int)
-(declare-const = (->(! Type :var T :implicit) T T Bool))
+(declare-const = (-> (! Type :var T :implicit) T T Bool))
 (declare-const + (-> Int Int Int))
 (declare-const - (-> Int Int Int))
 (declare-const < (-> Int Int Bool))
@@ -1452,7 +1453,7 @@ The above example recursively evaluates arithmetic terms and predicates accordin
       ((arith.typeunion Real Real) Real)
     )
 )
-(declare-const + (->(! Type :var T :implicit)
+(declare-const + (-> (! Type :var T :implicit)
                      (! Type :var U :implicit)
                      T U (arith.typeunion T U)))
 ```
@@ -1466,9 +1467,9 @@ The return type of `+` invokes this side condition, which conceptually is implem
 ```smt
 (declare-type String ())
 (declare-consts <string> String)
-(declare-const not (->Bool Bool))
-(declare-const or (->Bool Bool Bool) :right-assoc-nil false)
-(declare-const and (->Bool Bool Bool) :right-assoc-nil true)
+(declare-const not (-> Bool Bool))
+(declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
+(declare-const and (-> Bool Bool Bool) :right-assoc-nil true)
 
 (program to_drat_lit ((l Bool))
   (Bool) Int
@@ -1556,8 +1557,8 @@ Also, similar to programs, the free parameters of `ri` that occur in the paramet
 
 ```smt
 (declare-type Int ())
-(declare-const = (->(! Type :var T :implicit) T T Bool))
-(declare-const not (->Bool Bool))
+(declare-const = (-> (! Type :var T :implicit) T T Bool))
+(declare-const not (-> Bool Bool))
 (declare-rule symm ((F Bool))
     :premises (F)
     :conclusion
@@ -1577,8 +1578,8 @@ Internally, the semantics of `eo::match` can be seen as an (inlined) program app
 
 ```smt
 (declare-type Int ())
-(declare-const = (->(! Type :var T :implicit) T T Bool))
-(declare-const not (->Bool Bool))
+(declare-const = (-> (! Type :var T :implicit) T T Bool))
+(declare-const not (-> Bool Bool))
 (program matchF ((t1 Int) (t2 Int))
     (Bool) Bool
     (
@@ -1600,8 +1601,8 @@ In more general cases, if the body of the match term contains free variables, th
 
 ```smt
 (declare-type Int ())
-(declare-const = (->(! Type :var T :implicit) T T Bool))
-(declare-const and (->Bool Bool Bool) :left-assoc)
+(declare-const = (-> (! Type :var T :implicit) T T Bool))
+(declare-const and (-> Bool Bool Bool) :left-assoc)
 
 (program mk_trans ((t1 Int) (t2 Int) (t3 Int) (t4 Int) (tail Bool :list))
     (Int Int Bool) Bool
@@ -1660,7 +1661,7 @@ For example:
 (declare-type Int ())
 (declare-type Real ())
 (declare-const / (-> Int Int Real))
-(program normalize ((T Type) (S Type) (f (->S T)) (x S) (a Int) (b Int))
+(program normalize ((T Type) (S Type) (f (-> S T)) (x S) (a Int) (b Int))
    (T) T
    (
      ((normalize (/ a b)) (eo::qdiv a b))
@@ -1694,7 +1695,7 @@ Ground applications of oracle functions are eagerly evaluated by invoking the bi
 ```smt
 (declare-type Int ())
 (declare-consts <numeral> Int)
-(declare-const = (->(! Type :var T :implicit) T T Bool))
+(declare-const = (-> (! Type :var T :implicit) T T Bool))
 (declare-const >= (-> Int Int Bool))
 
 (declare-oracle-fun runIsPrime (Int) Bool ./isPrime)
@@ -1871,12 +1872,12 @@ Proof checking can be seen as a special instance of type checking terms involvin
 The type system of the Ethos can be summarized as follows, where `t : S` are assumed axioms for all atomic terms `t` of type `S`:
 
 ```smt
-f : (->(Quote u) S)  t : T
+f : (-> (Quote u) S)  t : T
 ---------------------------- if u * sigma = t
 (f t) : S * sigma
 
 
-f : (->U S)  t : T
+f : (-> U S)  t : T
 ------------------- if U * sigma = T
 (f t) : S * sigma
 
@@ -1899,7 +1900,7 @@ can be seen as syntax sugar for:
 
 ```smt
 (declare-const s
-    (->(! T1 :var v1 :implicit) ... (! Ti :var vi :implicit)
+    (-> (! T1 :var v1 :implicit) ... (! Ti :var vi :implicit)
         (Proof p1) ... (Proof pn)
         (Quote t1) ... (Quote tm)
         (eo::requires r1 s1 ... (eo::requires rk sk

From 5c779a16c575763bb933e56cdf9cf56af32105d6 Mon Sep 17 00:00:00 2001
From: Cesare Tinelli <cesare-tinelli@uiowa.edu>
Date: Wed, 4 Sep 2024 16:56:30 -0500
Subject: [PATCH 03/12] Added back some text from previous commits

---
 user_manual.md | 123 +++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 109 insertions(+), 14 deletions(-)

diff --git a/user_manual.md b/user_manual.md
index e9bfbce9..6bf27dc0 100644
--- a/user_manual.md
+++ b/user_manual.md
@@ -257,6 +257,56 @@ Symbol `eo::is_neg` denotes a builtin function that returns `true` if its argume
 > __Note:__ Internally, `(! T :requires (t s))` is syntax sugar for the type term `(eo::requires t s T)` where `eo::requires` is an operator that evaluates to its third argument if and only if its first two arguments are _computationally_ equivalent (details on this operator are given in [computation](#computation))<!--CT This is non-ideal from a language design point of view as it makes the semantic of Eunoia non-compositional: the meaning of `eo::requires` applications changes depending on whether there are in positive or negative positions. -->.
 Furthermore, the function type `(-> (eo::requires t s T) S)` is treated as `(-> T (eo::requires t s S))`. Ethos rewrites all types of the former form to the latter.
 
+
+<a name="opaque"></a>
+
+### The :opaque annotation
+
+The attribute `:opaque` can be used to denote that a distinguished argument to a function.
+In particular, functions with opaque arguments intuitively can be considered a _family_ of functions indexed by their opaque arguments.
+An example of this annotation is the following:
+
+```smt
+(declare-type Array (Type Type))
+(declare-const @array_diff
+   (-> (! Type :var T :implicit) (! Type :var U :implicit)
+   (! (Array T U) :opaque)
+   (! (Array T U) :opaque)
+   T))
+
+(declare-type Int ())
+(declare-const A (Array Int Int))
+(declare-const B (Array Int Int))
+(define d () (@array_diff A B) :type Int)
+```
+
+The above example declares a function `@array_diff` symbol.
+This has two implicit type arguments `T` and `U` followed by two opaque array arguments and has `T` as a return type.
+In the remainder of the example, we define `d` to be this function applied to the arrays `A` and `B`, where `d` has type `Int`.
+
+Intuitively, `d` should be considered an atomic constant symbol, where `A` and `B` are its indices and not its children.
+In particular, this means that any computation that pattern matches `d` will not consider it to be a function application.
+We give examples of this later in [ex-substitution](#ex-substitution).
+
+Functions can have both opaque and ordinary arguments, where the opaque arguments are expected to come first.
+The concatenation of the expected arguments can be passed to the symbol in the order they are given.
+For example:
+
+```smt
+(declare-type Int ())
+(declare-const @purify_fun (-> (! (-> Int Int) :opaque) Int Int))
+
+(declare-const f (-> Int Int))
+(declare-const a Int)
+(define d () (@purify_fun f a) :type Int)
+```
+
+In this example, `@purify_fun` is declared as a function with one opaque argument, and ordinary integer argument, and returns an integer.
+Intuitively, this definition is introducing a new function, indexed by a function, that is of type `(-> Int Int)`.
+After parsing, the term `(@purify_fun f a)` is a function application whose operator is `(@purify_fun f)` and has a single child `a`.
+
+> __Note:__ Opaque arguments should always be expected before other arguments. Otherwise all applications of the given function will be ill-typed.
+
 <a name="attributes"></a>
 
 ### Declarations with attributes
@@ -498,13 +548,16 @@ A variable list parsed in this way binds the symbol `x` to a variable of type `I
 The variable list passed as the first argument to the binder is determined by applying the specified constructor (in this case `@cons`) to the list of variables, so that `(forall ((x Int)) (P x))` is syntax sugar for `(forall (@cons x) (P x))`.
 The constructor specified in declarations of binders should accept a variable number of arguments, e.g. `@cons` is declared with attribute `:right-assoc-nil`.
 
-Variables introduced when parsing binders are always the same for each (symbol, type) pair unless the option `--binder-fresh` is enabled, in which case the variable is always unique.
+Variables introduced when parsing binders are always the same for each (symbol, type) pair.
 In particular, this means that the definitions of `Q1` and `Q2` are syntactically identical in the above example.
 On the other hand, the definition `Q3` is distinct from both of these, since `y` is a distinct variable from `x`.
 
 Furthermore, note that a binder also may accept an explicit term as its first argument.
 In the above example, `Q4` has `(@cons x)` as its first argument, where `x` was explicitly defined as a variable.
-This means that the definition of `Q4` is also syntactically equivalent to the definition of `Q1` and `Q2`, again assuming that `--binder-fresh` is not enabled.
+This means that the definition of `Q4` is also syntactically equivalent to the definition of `Q1` and `Q2`.
+
+Note that if the option `--binder-fresh` is enabled, then when parsing reference files, the variables in binders are always fresh.
+This option does not impact how binders are parsed in Eunoia files.
 
 <a name="literals"></a>
 
@@ -519,8 +572,10 @@ The Eunoia language supports associating SMT-LIB version 3.0 syntactic categorie
 - `<hexadecimal>` denoting the category of hexadecimal constants `#x<hex-digit>+` where hexdigit is `[0-9] | [a-f] | [A-F]`,
 - `<string>` denoting the category of string literals `"<char>*"`.
 
-By default, decimal literals will be treated as syntax sugar for rational literals unless the option `--no-normalize-dec` is enabled.
+When parsing proofs and reference files, by default, decimal literals will be treated as syntax sugar for rational literals unless the option `--no-normalize-dec` is enabled.
 Similarly, hexadecimal literals will be treated as syntax sugar for binary literals unless the option `--no-normalize-hex` is enabled.
+Some SMT-LIB logics (e.g. `QF_LRA`) state that numerals should be treated as syntax sugar for rational literals.
+This behavior can be enabled when parsing proofs and reference files using the option `--normalize-num`.
 
 In contrast to SMT-LIB version 2, note that rational values can be specified directly using the syntax `5/11, 2/4, 0/1` and so on.
 Rationals are normalized so that e.g. `2/4` and `1/2` are syntactically equivalent after parsing.
@@ -620,9 +675,9 @@ Note however that the evaluation of these operators is handled by more efficient
 - `(eo::is_z t)`
   - Equivalent to `(eo::is_eq (eo::to_z t) t)`.
 - `(eo::is_q t)`
-  - Equivalent to `(eo::is_eq (eo::to_q t) t)`. Note this returns false for decimal literals when `--no-normalize-dec` is enabled.
+    - Equivalent to `(eo::is_eq (eo::to_q t) t)`. Note this returns false for decimal literals.
 - `(eo::is_bin t)`
-  - Equivalent to `(eo::is_eq (eo::to_bin (eo::len t) t) t)`. Note this returns false for hexadecimal literals  when `--no-normalize-hex` is enabled.
+    - Equivalent to `(eo::is_eq (eo::to_bin (eo::len t) t) t)`. Note this returns false for hexadecimal literals.
 - `(eo::is_str t)`
   - Equivalent to `(eo::is_eq (eo::to_str t) t)`.
 - `(eo::is_bool t)`
@@ -726,12 +781,10 @@ The Ethos supports extensions of `eo::and, eo::or, eo::xor, eo::add, eo::mul, eo
 (eo::add 1/2 1/3)           == 5/6
 (eo::add 2 1/3)             == (eo::add 2 1/3)  ; no mixed arithmetic
 (eo::add 2/1 1/3)           == 7/3
-(eo::add 2.0 1/3)           == 7/3  ; with default options
-(eo::add 2.0 1/3)           == (eo::add 2.0 1/3)  ; if --no-normalize-dec is enabled, since no mixed arithmetic
-(eo::add 2.0 2.5)           == 4.5  ; which is not syntactically equal to 9/2 if --no-normalize-dec is enabled
+(eo::add 2.0 1/3)           == (eo::add 2.0 1/3)  ; since no mixed arithmetic
+(eo::add 2.0 2.5)           == 4.5
 (eo::add #b01 #b01)         == #b10
-(eo::add #x1 #b0001)        == #b0002  ; with default options
-(eo::add #x1 #b0001)        == (eo::add #x1 #b0001)  ; if --no-normalize-hex is enabled
+(eo::add #x1 #b0001)        == (eo::add #x1 #b0001)  ; since no mixed arithmetic
 (eo::mul 2 7)               == 14
 (eo::mul 2 2 7)             == 28
 (eo::mul 1/2 1/4)           == 1/8
@@ -739,7 +792,7 @@ The Ethos supports extensions of `eo::and, eo::or, eo::xor, eo::add, eo::mul, eo
 (eo::qdiv 12 6)             == 3/1
 (eo::qdiv 7 2)              == 7/2
 (eo::qdiv 7/1 2/1)          == 7/2
-(eo::qdiv 7.0 2.0)          == 7/2  ; regardless of whether --no-normalize-dec is enabled
+(eo::qdiv 7.0 2.0)          == 7/2
 (eo::qdiv 7 0)              == (eo::qdiv 7 0)  ; no division by zero
 (eo::zdiv 12 3)             == 4
 (eo::zdiv 7 2)              == 3
@@ -1412,6 +1465,26 @@ In detail, recall that the Ethos treats all function applications as curried (un
 In particular, this implies that `(f a)` matches any application term, since both `f` and `a` are parameters.
 Thus, the side condition is written in three cases: either `t` is `x` in which case we return `y`, `t` is a function application in which case we recurse, or otherwise `t` is a constant not equal to `x` and we return itself.
 
+This method will not replace subterms inside of opaque arguments (see [opaque](#opaque)).
+In particular, a term such as `(@array_diff A B)` will remain unchanged for a substitution e.g. replacing `A` with `B`, since `(@array_diff A B)` is not a function application.
+Hence when `t` is `(@array_diff A B)`, we fall into the third case of the method above for any call to `substitute` where `x` is not `(@array_diff A B)` itself.
+
+Alternatively, the following version of substitution `substitute-o` pattern matches on applications of `@array_diff` explicitly.
+Calling it with arguments `A`, `B`, and `(@array_diff A B)` would return `(@array_diff B B)`.
+
+```smt
+(program substitute-o
+  ((T Type) (U Type) (S Type) (x S) (y S) (a (Array T U)) (b (Array T U)) (z U))
+  (S S U) U
+  (
+  ((substitute-o x y x)                 y)
+  ((substitute-o x y (f a))             (_ (substitute-o x y f) (substitute-o x y a)))
+  ((substitute-o x y (@array_diff a b)) (@array_diff (substitute-o x y a) (substitute-o x y b)))
+  ((substitute-o x y z)                 z)
+  )
+)
+```
+
 ### Example: Term evaluator
 
 ```smt
@@ -1749,9 +1822,31 @@ The Ethos command line interface can be invoked by `ethos <option>* <file>` wher
 - `-t <tag>`: enables the given trace tag (for debugging).
 - `-v`: verbose mode, enable all standard trace messages.
 
-### Full syntax for Eunoia commands
+The following options impact how proof files and reference files are parsed only (for details on classifications of files, see [full-syntax](#full-syntax)).
+They do not impact how signature files (*.eo) are parsed:
+
+- `--binder-fresh`: binders generate fresh variables.
+- `--normalize-num`: treat numeral literals as syntax sugar for (integral) rational literals.
+- `--no-normalize-dec`: do not treat decimal literals as syntax sugar for rational literals.
+- `--no-normalize-hex`: do not treat hexadecimal literals as syntax sugar for binary literals.
+- `--no-parse-let`: do not treat `let` as a builtin symbol for specifying a macro.
+
+<a name="full-syntax"></a>
+
+## Full syntax for Eunoia commands
+
+Below defines the syntax accepted by the Ethos parser.
+
+We distinguish three kinds of file inputs:
+
+- _Proof files_ are files that are given via command line option that do _not_ have extension `*.eo`.
+Their expected syntax is `<eo-command>*`.
+- _Reference files_ are files included via the `reference` command.
+Their expected syntax is `<smtlib2-command>*`.
+- _Signature files_ are files that given via command line option that have extension `*.eo`, or those that are included via the command `include`.
 
-Valid inputs to the Ethos are `<eo-command>*`, where:
+As mentioned, the first two kinds of file inputs take into account options concerning the normalization of terms (e.g. `--normalize-num`), while signature files do not.
+When streaming input to Ethos, we assume the input is being given for a proof file.
 
 ```smt
 ;;;
@@ -1860,7 +1955,7 @@ The following signature can be used to define operators that are not required to
 
 ; An arbitrary deterministic comparison of terms. Returns true if a > b based
 ; on this ordering.
-(define eo::com ((T Type :implicit) (U Type :implicit) (a T) (b U))
+(define eo::cmp ((T Type :implicit) (U Type :implicit) (a T) (b U))
   (eo::is_neg (eo::add (eo::hash b) (eo::neg (eo::hash a)))))
 
 ```

From 1fa108fd3a2a07f9227047e316dcd3f286153343 Mon Sep 17 00:00:00 2001
From: Cesare Tinelli <cesare-tinelli@uiowa.edu>
Date: Thu, 5 Sep 2024 10:18:25 -0500
Subject: [PATCH 04/12] Apply suggestions from code review

Co-authored-by: Andrew Reynolds <andrew.j.reynolds@gmail.com>
---
 user_manual.md | 36 +++++++++++++++++-------------------
 1 file changed, 17 insertions(+), 19 deletions(-)

diff --git a/user_manual.md b/user_manual.md
index 6bf27dc0..6930a173 100644
--- a/user_manual.md
+++ b/user_manual.md
@@ -60,7 +60,7 @@ The `ethos` binary accepts input piped from stdin. The following are all equival
 Eunoia is the name of the logical framework and language that is supported natively by the Ethos checker.
 Although it is a general logical framework, Eunoia is geared towards defining proof systems used by SMT solvers and writing proofs in those systems.
 
-Eunoia files are text file that are typically given the suffix `*.eo`.
+Eunoia files are text files that are typically given the suffix `*.eo`.
 
 The core features of Eunoia include:
 
@@ -70,7 +70,7 @@ The core features of Eunoia include:
 - A set of commands for specifying proofs (`step`, `assume`, and so on), whose syntax closely follows that of the Alethe proof format (for details, see [here](https://verit.gitlabpages.uliege.be/alethe/specification.pdf)).
 - A set of built-in basic types and a library of operations (`eo::add`, `eo::mul`, `eo::concat`, `eo::extract`) for performing computations over values.
   <!--CT It would be more consistent with the rest of the terminology to use `define-program` instead -->
-- A command, `program`, for defining side conditions as ordered list of rewrite rules.
+- A command, `program`, for defining side conditions as an ordered list of rewrite rules.
 - A command, `declare-oracle-fun`, for defining external, user-provided oracles, that is, functions whose semantics are given by external binaries. Oracles can be used, e.g., for modular proof checking.
 - Commands for file inclusion (`include`) and referencing (`reference`). The latter command can be used to specify the name of an `*.smt2` input file that the proof is associated with.
 
@@ -79,14 +79,14 @@ In the following sections, we describe these features in more detail. A full syn
 ### Declaring theory signatures
 
 In Eunoia, as in SMT-LIB version 3.0, a common BNF is used to specify _terms_ (expressions denoting values), _types_ (expressions denoting sets of values) and _kinds_ (expressions denoting sets of types).
-In this document, unless specified otherwise, we will use _term_ more generally to refer to a value term, a type, or a kind
+In this document, unless specified otherwise, we will use _term_ more generally to refer to a value term, a type, or a kind.
 Terms are composed of applications, built-in operators of the language (e.g., for performing computations, see [computation](#computation)), literals (see [literals](#literals)), and three kinds of atomic terms (_constants_, _variables_, and _parameters_) which we describe in the following.
 A _function (symbol)_ is an atomic term having a function type, that is, a type of the form `(-> ... ...)`.
 The builtin `eo::define` binder can be used for specifying terms that contain common subterms analogously to `let` binders in other languages.
 
 The core language of Eunoia does not have any builtin SMT-LIB theories.
 Instead, SMT-LIB theories may defined as Eunoia signatures.
-To enable that, the Eunoia language has the following builtin constants:
+For this purpose, the Eunoia language has the following builtin constants:
 
 - `Type`, denoting the kind of all types,
 - `->`, denoting the function type,
@@ -196,7 +196,7 @@ Note the following declarations generate terms of the same type:
 ### The :type attribute for definitions
 
 To type check terms, `define` statements can be annotated with `:type <term>`.
-<!-- We should motivate this feature. Why is it there? -->
+This allows the user to eagerly check that a term has a particular type at the place where it is defined.
 In particular:
 
 ```smt
@@ -316,7 +316,6 @@ The Eunoia language supports term annotations on declared constants, which for i
 - `:right-assoc` (resp. `:left-assoc`) denoting that application of the declared binary constant to more than two terms are to be treated as right (resp. left) associative,
 
 - `:right-assoc-nil <term>` (resp. `:left-assoc-nil <term>`) denoting that applications of the declared binary constant to one or more terms are to be treated as right (resp. left) associative, with the given `<term>` used as an additional rightmost (resp. leftmost) argument.
-<!--CT Do we really want to restrict the nil element to be a symbol, as opposed to a term? -->
 
 - `:chainable <symbol>` denoting that the arguments of the declared binary constant are chainable using the (binary) operator given by `<symbol>`,
 
@@ -326,7 +325,7 @@ The Eunoia language supports term annotations on declared constants, which for i
 
 A declared function can be marked with at most one of the above attributes or an error is thrown.
 
-A parameter in a function symbol declaration may be marked with the following attribute:
+A parameter may be marked with the following attribute:
 
 - `:list`, denoting that the parameter should be treated as a list when appearing as a child of an application of a right (left) associative operator.
 
@@ -436,7 +435,8 @@ We instead require such declarations to be made with `declare-parameterized-cons
 
 #### List
 
-Atomic terms can be marked with the annotation `:list`.<!--CT Do we really need this level of generality? Can we restrict the annotation to just function arguments or perhaps just typed vars? -->
+Parameters can be marked with the annotation `:list`. 
+This includes those in function symbol declarations, as well as parameters to (e.g. `define`, `program`, `declare-rule`) commands.
 This annotation marks that the term should be treated as a list of arguments when it occurs as an argument of a right (left) associative operator with a nil element. Note the following example:
 
 ```smt
@@ -515,7 +515,7 @@ where the type of its chaining operator is `(-> S S S)`, and that operator has b
 In the above example, `(distinct x y z)` is treated as `(and (distinct x y) (distinct x z) (distinct y z))`.
 
 Note that the type for pairwise operators is typically `(-> T T S)` for some types `T` and `S`,
-where the type of its pairwise operator is `(-> S S S)`<!--CT This could be generalized, right? -->,
+where the type of its pairwise operator is `(-> S S S)`,
 and that operator has been marked as variadic via some attribute.
 
 <a name="binders"></a>
@@ -589,7 +589,7 @@ The only other escape sequences are of the form `\u{dn ...d1}` for `1<=n<=5` and
 
 > __Note:__ Numeral, rational and decimal values are implemented by the arbitrary precision arithmetic library GMP. Binary and hexadecimal values are implemented as layer on top of numeral values that tracks a bit width. String values are implemented as a vector of unsigned integers whose maximum value is specified by SMT-LIB version 2.6, namely the character set corresponds to Unicode values 0 to 196607.
 
-> __Note:__ The user is not required to declare that `true` and `false` are values of type `Bool`. Instead, it is assumed that the syntactic category `<boolean>` of Boolean values (`true` and `false`) has been associated with the Boolean sort. In other words, `(declare-consts <boolean> __Note:__Bool)` is a part of the builtin signature assumed by Ethos.
+> __Note:__ The user is not required to declare that `true` and `false` are values of type `Bool`. Instead, it is assumed that the syntactic category `<boolean>` of Boolean values (`true` and `false`) has been associated with the Boolean sort. In other words, `(declare-consts <boolean> Bool)` is a part of the builtin signature assumed by Ethos.
 
 <a name="declare-consts"></a>
 
@@ -1171,9 +1171,9 @@ If the keyword is `:ethos`, then the expected syntax that follows is given below
 (declare-rule <symbol> :ethos (<typed-param>*) <assumption>? <premises>? <arguments>? <reqs>? :conclusion <term> <attr>*)
 where
 <assumption>   ::= :assumption <term>
-<premises>     ::= :premises (<term>*) | :premise-list <term><term>
+<premises>     ::= :premises (<term>*) | :premise-list <term> <term>
 <arguments>    ::= :args (<term>*)
-<reqs>         ::= :requires ((<term><term>)*)
+<reqs>         ::= :requires ((<term> <term>)*)
 ```
 
 A proof rule begins by defining a list of free parameters, followed by 4 optional fields and a conclusion term.
@@ -1228,7 +1228,7 @@ Notice that the type `T` is a part of the parameter list and not explicitly prov
 ```
 
 This rule specifies symmetry of equality. This rule takes as premise an equality `(= t s)` and no arguments.
-In detail, an application of this proof rule for premise proof `(= a b)` for concrete terms `a,b` will compute the substitution `{ t ->a, s ->b }` and apply it to the conclusion term to obtain `(= b a)`.
+In detail, an application of this proof rule for premise proof `(= a b)` for concrete terms `a,b` will compute the substitution `{ t -> a, s -> b }` and apply it to the conclusion term to obtain `(= b a)`.
 
 ### Requirements
 
@@ -1341,7 +1341,7 @@ Locally assumptions can be arbitrarily nested, for example the above can be exte
 Similar to `declare-rule`, the Ethos supports an extensible syntax for programs whose generic syntax is given by:
 
 ```smt
-(program <symbol> > <keyword>? <sexpr>*)
+(program <symbol> <keyword>? <sexpr>*)
 ```
 
 When parsing this command, `ethos` will determine the format of the expected arguments based on the given keyword.
@@ -1667,7 +1667,7 @@ Internally, the semantics of `eo::match` can be seen as an (inlined) program app
 )
 ```
 
-> __Note:__ The Ethos automatically performs the above transformation on match terms for consistency.
+> __Note:__ The Ethos checker automatically performs the above transformation on match terms for consistency.
 In more general cases, if the body of the match term contains free variables, these are added to the argument list of the internally generated program.
 
 ### Example: Proof rule for transitivity of equality with a premise list
@@ -1708,7 +1708,7 @@ The Ethos supports the following commands for file inclusion:
 
 ### Validation Proofs via Reference Inputs
 
-When the Ethos encounters a command of the form `(reference <string>)`, the checker enables a further set of checks that ensures that all assumptions in proofs correspond to assertions from the reference file.
+When the Ethos encounters a command of the form `(reference <string>)`, the checker enables a further set of checks that ensures that all assumptions in proofs correspond to assertions from the file referenced by the given string.
 
 In particular, when the command `(reference "file.smt2")` is read, the Ethos will parse `file.smt2`.
 The definitions and declaration commands in this file will be treated as normal, that is, they will populate the symbol table of the Ethos as they normally would if they were to appear in an `*.eo` input.
@@ -1800,7 +1800,7 @@ After successfully parsing an input file with no errors, the Ethos will respond
 - `incomplete` if it parsed any `step` or `step-pop` application that referenced a proof rule that was marked with the attribute `:sorry`, or
 - `correct` otherwise.
 
-Note however that the Ethos does not impose any requirements on _what_ was proven in the proof.
+Note however that Ethos does not impose any requirements on _what_ was proven in the proof.
 The user is responsible for ensure that e.g. the proof contains a step with a desired conclusion (e.g. `false`).
 
 ## Appendix
@@ -1914,8 +1914,6 @@ When streaming input to Ethos, we assume the input is being given for a proof fi
 
 ```
 
-Moreover, a valid input for a file included by the Eunoia command `<reference>` is `<smtlib2-command>*`;
-a valid input for a file included by the Eunoia command `<include>` is `<eo-command>*`.
 
  <a name="non-core-eval"></a>
 

From 0dcd06de7ccc1ecd5864ea6966be073a2d44fa0f Mon Sep 17 00:00:00 2001
From: Cesare Tinelli <cesare-tinelli@uiowa.edu>
Date: Thu, 5 Sep 2024 23:39:05 -0500
Subject: [PATCH 05/12] Removed most comments

---
 user_manual.md | 74 +++++++++++++++++---------------------------------
 1 file changed, 25 insertions(+), 49 deletions(-)

diff --git a/user_manual.md b/user_manual.md
index 6930a173..3119c671 100644
--- a/user_manual.md
+++ b/user_manual.md
@@ -106,7 +106,6 @@ The following commands are supported for declaring and defining types and terms.
 - `(declare-consts <lit-category> <type>)` declares the class of symbols denoted by the literal category to have the given type.
 
 - `(declare-type <symbol> (<type>*))` declares a new type constructor named `<symbol>` whose kind is `Type` if `<type>*` is empty. If `<type>*` is `<type_1> ... <type_n>`, then kind of `<symbol>` is `(-> <type_1> ... <type_n> Type)`.
-  <!-- Added-->
   This is a derived command as it is a shorthand for
   `(declare-const <symbol> Type)` if `<type>*` is empty, and for
   `(declare-const <symbol> (-> <type>* Type))` otherwise.
@@ -141,9 +140,9 @@ The Eunoia language contains further commands for declaring symbols that are not
 (declare-const P (-> Int Bool))
 ```
 
-Since Ethos does not assume any builtin definitions of SMT-LIB theories, definitions of standard symbols (such as `Int`) may be provided in Eunoia signatures<!--CT I bet this point is going to be confusing to users. -->. In the above example, symbol `c` is declared to be a constant (0-ary) symbol of type `Int`. The symbol `f` is a function taking two integers and returning an integer.
+Since Ethos does not assume any builtin definitions of SMT-LIB theories, definitions of standard symbols in SMT-LIB theories(such as `Int`, `+`, etc.) must be provided in Eunoia signatures. In the above example, symbol `c` is declared to be a constant (0-ary) symbol of type `Int`. The symbol `f` is a function taking two integers and returning an integer.
 
-Observe that despite using different syntax in their declarations, the types of `f` and `g` in the above example are identical as `->` is a right-associative binary type constructor.
+Observe that despite the use of different syntax in their declarations, the types of `f` and `g` in the above example are identical as `->` is a right-associative binary type constructor.
 
 > __Note:__ In Eunoia, all functions are unary. In the above example, `(-> Int Int Int)` is internally treated as `(-> Int (-> Int Int))`. Correspondingly, applications of functions are curried, e.g. `(f a b)` is treated as `((f a) b)`, which in turn can be seen as `(_ (_ f a) b)` where `_` denotes higher-order function application.
 
@@ -226,7 +225,6 @@ In contrast, the example below declares a predicate `=` where the type of the ar
 (define P ((x Int) (y Int)) (= x y))
 ```
 
-<!--CT Added -->
 In general, an argument can be made implicit if its value can be inferred from the type of later arguments.
 
 We call `T` in the above definitions a _parameter_. The free parameters of the return type of an expression should be contained in at least one non-implicit argument. In particular, the following declaration is malformed, since the return type of `f` cannot be inferred from its arguments:
@@ -254,10 +252,9 @@ The second annotation indicates that the term `(eo::is_neg w)` must evaluate to
 Symbol `eo::is_neg` denotes a builtin function that returns `true` if its argument is a negative numeral, and returns false otherwise (for details, see [computation](#computation)).
 <!-- This needs discussion, what is the input type of `eo::is_neg`? How can `eo::is_neg` accept a value of a user-defined type `Int` given that it is builtin?  -->
 
-> __Note:__ Internally, `(! T :requires (t s))` is syntax sugar for the type term `(eo::requires t s T)` where `eo::requires` is an operator that evaluates to its third argument if and only if its first two arguments are _computationally_ equivalent (details on this operator are given in [computation](#computation))<!--CT This is non-ideal from a language design point of view as it makes the semantic of Eunoia non-compositional: the meaning of `eo::requires` applications changes depending on whether there are in positive or negative positions. -->.
+> __Note:__ Internally, `(! T :requires (t s))` is syntax sugar for the type term `(eo::requires t s T)` where `eo::requires` is an operator that evaluates to its third argument if and only if its first two arguments are _computationally_ equivalent (details on this operator are given in [computation](#computation)).
 Furthermore, the function type `(-> (eo::requires t s T) S)` is treated as `(-> T (eo::requires t s S))`. Ethos rewrites all types of the former form to the latter.
 
-
 <a name="opaque"></a>
 
 ### The :opaque annotation
@@ -370,40 +367,39 @@ Eunoia supports a variant of the aforementioned functionality where a (ground) n
 In the above example, `(or x y z)` is treated as `(or x (or y (or z false)))`,
 `(or x y)` is treated as `(or x (or y false))`,
 and `(or x)` is treated as `(or x false)`.
-<!--CT added -->In contrast, if `or` was annotated with `left-associative-nil`,
+In contrast, if `or` was annotated with `left-associative-nil`,
 `(or x y z)` would be treated as `(or (or (or false x) y) z)`,
 `(or x y)` as `(or (or false x) y)`,
 and `(or x)` as `(or false x)`.
 
 The advantage of right or left associative operators with nil terminators is that the terms they specify are unambiguous, which is not the case for right or left associative operators without nil terminators.
-In particular, note the following example:
+Consider the following example:
 
 ```smt
 (declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
-(define P ((x Bool) (y Bool) (z Bool)) (or x (or y z)))
-(define Q ((x Bool) (y Bool) (z Bool)) (or x y z))
+(define P1 ((x Bool) (y Bool) (z Bool)) (or x (or y z)))
+(define P2 ((x Bool) (y Bool) (z Bool)) (or x y z))
 ```
 
-<!--CT We should stress that we get to different AST for the P and Q above.
--->
-
- <!--CT We should point out that the nil element should be a left and right identity of the assoc symbol, otherwise non-intuitive results occur. 
+If `or` had been marked `:right-assoc`, after desugaring, the abstract syntax tree for (the terms named) `P2` would have been the same `P1`.
+In contrast, marking `or` with `:right-assoc-nil false` leads after desugaring to the distinct terms
 
-For instance, with
-(declare-const + (-> Int Int Int) :right-assoc-nil 1)
-We have that 
-(+ x (+ y z))) = (+ x (+ (+ y (+ z 1)) 1)) = x + y + z + 2
-is not equivalent to
-(+ x (+ y (+ z 1))) = x + y + z + 1
-However, I would use this example not to argue that it is advantageous to use the :[left|right]-associative-nil annotation but to warn the reader that the nil element better be a left/right identity for the binary operator, otherwise the semantic is highly unintuitive.
--->
+- `(or x (or (or y (or z false)) false))` for `P1` and
+- `(or x (or y (or z false)))` for `P2`.
 
-If `or` had been marked `:right-assoc`, then the definition of both `P` and `Q` would be `(or x (or y z))` after desugaring.
-In contrast, marking `or` with `:right-assoc-nil false` leads to the distinct terms `(or x (or (or y (or z false)) false))` and `(or x (or y (or z false)))` after desugaring.
+> __Note:__ While the value provided for the `:right-assoc-nil` attribute (`false` in the example above) can be an arbitrary term of the proper type, it is advisable for it to be a _neutral_, or identity, element of the binary operator in question (`or` in the example). Otherwise, this gives rise to non-intuitive syntax.
+>
+> For instance, with
+>
+> ```smt
+> (declare-const + (-> Int Int Int) :right-assoc-nil 1)
+> ```
+>
+> where `+` is meant to be the integer addition operator, the choice of `1` as terminator instead of the identity element `0` means that the expressions `(+ x (+ y z)))` and `(+ x y z)` desugar to terms (`(+ x (+ (+ y (+ z 1) 1)))` and `(+ x (+ y (+ z 1)))`, respectively) that are distinct not just syntactically but also semantically.
 
 Right and left associative operators with nil terminators also have a relationship with list terms (as we will see in the following section), and in computational operators.
 
-The type for right and left associative operators with nil terminators is typically `(-> T T T)` for some `T`, where their nil terminator has type `T`. <!--CT Added.--> More generally, a constant declared with the `:right-associative-nil` annotation must have a type of the form `(-> T1 T2 T2)` where `T2` is the type of the nil constant, for some types `T1` and `T2`. Similarly, a constant declared with the `:left-associative` annotation must have a type of the form `(-> T1 T2 T1)` where `T1` is the type of the nil constant.
+The type for right and left associative operators with nil terminators is typically `(-> T T T)` for some `T`, where their nil terminator has type `T`. More generally, a constant declared with the `:right-associative-nil` annotation must have a type of the form `(-> T1 T2 T2)` where `T2` is the type of the nil constant, for some types `T1` and `T2`. Similarly, a constant declared with the `:left-associative` annotation must have a type of the form `(-> T1 T2 T1)` where `T1` is the type of the nil constant.
 
 The nil terminator of a right associative operator may involve previously declared symbols in the signature.
 For example:
@@ -435,7 +431,7 @@ We instead require such declarations to be made with `declare-parameterized-cons
 
 #### List
 
-Parameters can be marked with the annotation `:list`. 
+Parameters can be marked with the annotation `:list`.
 This includes those in function symbol declarations, as well as parameters to (e.g. `define`, `program`, `declare-rule`) commands.
 This annotation marks that the term should be treated as a list of arguments when it occurs as an argument of a right (left) associative operator with a nil element. Note the following example:
 
@@ -460,6 +456,7 @@ In other words, the definitions of `Paab` and `Qaab` are equivalent to the terms
 
 More generally, for an right-associative operator `f` with nil terminator `nil`,
 the term `(f t1 ... tn)` is de-sugared based on whether each `t1 ... tn` is marked with `:list`.
+
 - The nil terminator is inserted at the tail of the function application unless `tn` is marked as `:list`,
 - If `ti` is marked as `:list` where `1<=i<n`, then `ti` is prepended to the overall application using a concatentation operation `eo::list_concat`. The semantics of this operator is provided later in [list-computation](#list-computation).
 
@@ -522,8 +519,6 @@ and that operator has been marked as variadic via some attribute.
 
 #### Binder
 
-<!--CT Section to be reviewed further -->
-
 ```smt
 (declare-type Int ())
 (declare-type @List ())
@@ -637,29 +632,9 @@ Note however that the evaluation of these operators is handled by more efficient
 - `(eo::is_eq t1 t2)`
   - Returns `true` if `t1` is (syntactically) equal to `t2`, or `false` if `t1` and `t2` are distinct and ground. Otherwise, it does not evaluate.
 
- <!--CT To be discussed with Andy
-    $$[(\textsf{eo::is_eq}\ t_1\ t_2)] =
-    \begin{cases}
-     \textsf{true} & \text{if } [t_1], [t_2] \text{ are identical} \\
-     \textsf{false} & \text{if } [t_1], [t_2] \text{ are distinct and ground} \\
-     (\textsf{eo::is_eq}\ t_1\ t_2) & \text{otherwise}
-    \end{cases}
-    $$
--->
-
 - `(eo::ite t1 t2 t3)`
   - Returns `t2` if `t1` evaluates to `true`, `t3` if `t2` evaluates to `false`, and is not evaluated otherwise. Note that the branches of this term are only evaluated if they are the return term.
 
- <!--CT To be discussed with Andy
-    $$[(\textsf{eo::ite}\ t_1\ t_2\ t_3)] =
-    \begin{cases}
-     [t_2] & \text{if } [t_1] = \textsf{true} \\
-     [t_3] & \text{if } [t_1] = \textsf{false} \\
-     (\textsf{eo::ite}\ t_1\ t_2\ t_3) & \text{otherwise}
-    \end{cases}
-    $$
--->
-
 - `(eo::requires t1 t2 t3)`
   - Returns `t3` if `t1` is (syntactically) equal to `t2`, and is not evaluated otherwise.
 - `(eo::hash t1)`
@@ -1756,9 +1731,11 @@ We reference to such functions as _oracle functions_.
 The syntax and semantics of such functions are described in this [paper](https://homepage.divms.uiowa.edu/~ajreynol/vmcai22a.pdf).
 
 In particular, the Ethos supports the command:
+
 ```smt
 (declare-oracle-fun <symbol> (<type>*) <type> <symbol>)
 ```
+
 Like the `declare-fun` command from SMT-LIB, this command declares a constant named `<symbol>` whose type is given by the argument types and return type.
 In addition, a symbol is provided at the end of the command which specifies the name of executable command to run.
 Ground applications of oracle functions are eagerly evaluated by invoking the binary and parsing its result, which we describe in more detail in the following.
@@ -1914,7 +1891,6 @@ When streaming input to Ethos, we assume the input is being given for a proof fi
 
 ```
 
-
  <a name="non-core-eval"></a>
 
 ### Definitions of Non-Core Evaluation Operators

From 68742069fb488170a2c3379fca090f4e76c9813b Mon Sep 17 00:00:00 2001
From: Cesare Tinelli <cesare-tinelli@uiowa.edu>
Date: Thu, 5 Sep 2024 23:41:20 -0500
Subject: [PATCH 06/12] Update .gitignore

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index 5acb669b..28d345a0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
 build
 .vscode
+.DS_Store

From a4b3390ce7a809707e894ed5549073213f2a33d9 Mon Sep 17 00:00:00 2001
From: Cesare Tinelli <cesare-tinelli@uiowa.edu>
Date: Wed, 4 Sep 2024 00:40:29 -0500
Subject: [PATCH 07/12] Introduced evaluation function [_] in Computational
 Operators section

---
 user_manual.md | 304 +++++++++++++++++++++++++++++++++----------------
 1 file changed, 208 insertions(+), 96 deletions(-)

diff --git a/user_manual.md b/user_manual.md
index 3119c671..cbf970ac 100644
--- a/user_manual.md
+++ b/user_manual.md
@@ -246,6 +246,7 @@ Arguments to functions can also be annotated with the attribute `:requires (<ter
 (declare-type Int ())
 (declare-const BitVec (-> (! Int :var w :requires ((eo::is_neg w) false)) Type))
 ```
+
 The above declares the integer type `Int` and a bitvector type constructor `BitVec` that expects a _non-negative integer_ `w`.
 In detail, the first argument of `BitVec` is supposed to be an `Int` value and is named `w` via the `:var` attribute.
 The second annotation indicates that the term `(eo::is_neg w)` must evaluate to `false` at type checking type.
@@ -458,7 +459,8 @@ More generally, for an right-associative operator `f` with nil terminator `nil`,
 the term `(f t1 ... tn)` is de-sugared based on whether each `t1 ... tn` is marked with `:list`.
 
 - The nil terminator is inserted at the tail of the function application unless `tn` is marked as `:list`,
-- If `ti` is marked as `:list` where `1<=i<n`, then `ti` is prepended to the overall application using a concatentation operation `eo::list_concat`. The semantics of this operator is provided later in [list-computation](#list-computation).
+
+- If `ti` is marked as `:list` where `1<=i<n`, then `ti` is prepended to the overall application using a concatenation operation `eo::list_concat`. The semantics of this operator is provided later in [list-computation](#list-computation).
 
 In detail, the returned term from desugaring `(f t1 ... tn)` is constructed inductively.
 If `tn` is marked with `:list`, the returned term is initialized to `tn` and we process children `ti` from `i = n-1 ... 1`.
@@ -560,31 +562,33 @@ This option does not impact how binders are parsed in Eunoia files.
 
 The Eunoia language supports associating SMT-LIB version 3.0 syntactic categories with types. In detail, a syntax category is one of the following:
 
-- `<numeral>` denoting the category of numerals `-?<digit>+`,
-- `<decimal>` denoting the category of decimals `-?<digit>+.<digit>+`,
-- `<rational>` denoting the category of rationals `-?<digit>+/<digit>+`,
-- `<binary>` denoting the category of binary constants `#b<0|1>+`,
-- `<hexadecimal>` denoting the category of hexadecimal constants `#x<hex-digit>+` where hexdigit is `[0-9] | [a-f] | [A-F]`,
-- `<string>` denoting the category of string literals `"<char>*"`.
+- `<boolean>` denoting the category of _Boolean_ literals `true | false`,
+- `<numeral>` denoting the category of (integer) _numerals_ `-?<digit>+`,
+- `<decimal>` denoting the category of _decimals_ `-?<digit>+.<digit>+`,
+- `<rational>` denoting the category of _rationals_ `-?<digit>+/<digit>+`,
+- `<binary>` denoting the category of _binary_ literals `#b<0|1>+`,
+- `<hexadecimal>` denoting the category of _hexadecimals_ `#x<hex-digit>+` where hexdigit is `[0-9] | [a-f] | [A-F]`,
+- `<string>` denoting the category of _strings_ literals `"<char>*"` <!--CT Added --> where `<char>` consists of the set of UTF-8 characters.
 
-When parsing proofs and reference files, by default, decimal literals will be treated as syntax sugar for rational literals unless the option `--no-normalize-dec` is enabled.
-Similarly, hexadecimal literals will be treated as syntax sugar for binary literals unless the option `--no-normalize-hex` is enabled.
-Some SMT-LIB logics (e.g. `QF_LRA`) state that numerals should be treated as syntax sugar for rational literals.
-This behavior can be enabled when parsing proofs and reference files using the option `--normalize-num`.
+<!--CT Added. -->
+We call _literal_ or _value_ any element of the seven syntactic categories above.
 
-In contrast to SMT-LIB version 2, note that rational values can be specified directly using the syntax `5/11, 2/4, 0/1` and so on.
-Rationals are normalized so that e.g. `2/4` and `1/2` are syntactically equivalent after parsing.
+<!--CT Added. -->
+> __Note:__ Numerals include _negated_ literals such as `-1`, `-43`, and so on. Also, and in contrast to SMT-LIB version 2, rational literals can be specified directly using the syntax `5/11`, `2/4`, `0/1` and so on, and negative values can be provided as single literals, e.g., `-1`, `-10.5`, `-1/3` and so on, instead of more complex expressions such as `(- 1)`, `(- 10.5)`, and `(/ (- 1) 3)`.
+
+By default, decimal literals are treated by Ethos as syntax sugar for rational literals unless the option `--no-normalize-dec` is enabled.
+Similarly, hexadecimal literals are treated as syntax sugar for binary literals unless the option `--no-normalize-hex` is enabled.
+Rationals are normalized so that, e.g., `2/4` and `1/2` are syntactically equivalent after parsing.
 Similarly, decimals are normalized so that e.g. `1.300` is syntactically equivalent to `1.3` after parsing.
 Note this is independent of whether these decimal values are further normalized to rational values.
 In other words, by default `1.300` is syntactically equivalent to the rational `13/10`.
-Also note in contrast to SMT-LIB version 2, negative arithmetic can be provided using the syntax e.g. `-1, -10.5, -1/3` and so on, instead of `(- 1), (- 10.5), (/ (- 1) 3)`.
 
 String values use the standard escape sequences as specified in SMT-LIB version 2.6, namely `""` within a string literal denotes `"`.
 The only other escape sequences are of the form `\u{dn ...d1}` for `1<=n<=5` and `\u d4 d3 d2 d1` for hexadecimal digits `d1...d5` where `d5` is in the range `[0-2]`.
 
 > __Note:__ Numeral, rational and decimal values are implemented by the arbitrary precision arithmetic library GMP. Binary and hexadecimal values are implemented as layer on top of numeral values that tracks a bit width. String values are implemented as a vector of unsigned integers whose maximum value is specified by SMT-LIB version 2.6, namely the character set corresponds to Unicode values 0 to 196607.
 
-> __Note:__ The user is not required to declare that `true` and `false` are values of type `Bool`. Instead, it is assumed that the syntactic category `<boolean>` of Boolean values (`true` and `false`) has been associated with the Boolean sort. In other words, `(declare-consts <boolean> Bool)` is a part of the builtin signature assumed by Ethos.
+> __Note:__ Except for `<boolean>`, the literal categories above are not associated to any type by default. The user must decides what type to assign to each of them, with the command `declare-consts`. In contrast, the values of `<boolean>` have the predefined type `Bool`. In other words, `(declare-type Bool ())` and `(declare-consts <boolean> Bool)` are part of the builtin signature assumed by Ethos.
 
 <a name="declare-consts"></a>
 
@@ -611,138 +615,246 @@ The signature can now refer to arbitrary numerals in definitions, e.g. `7` in th
 
 The Ethos has builtin support for computations over all syntactic categories of SMT-LIB version 3.0.
 We list the operators below, roughly categorized by domain.
-However, note that the operators are polymorphic and in some cases can be applied to multiple syntactic categories.
-For example, `eo::add` returns the result of adding two integers or rationals, but also can be used to add binary constants (integers modulo a given bitwidth).
-Similarly, `eo::concat` returns the result of concatenating two string literals, but can also concatenate binary constants.
+<!--CT Added -->
+Note that all the operators operate on _terms_, _regardless_ of the user-defined type
+assigned to those terms. The behavior of each operator is based only on the syntax of its input terms, not their types.
+
+Some of the operators are overloaded, i.e., they can be applied to multiple syntactic categories, with different behavior for each category.
+For example, `eo::add` returns the result of adding two numerals or rationals, but also can be used to add binary values (integers modulo a given bit width).
+Similarly, `eo::concat` returns the result of concatenating two string values, but can also concatenate two binary values.
 We remark on the semantics in the following.
 
 In the following, we say a term is _ground_ if it contains no parameters as subterms.
-We say an _arithmetic value_ is a numeral, decimal or rational value.
-We say a _bitwise value_ is a binary or hexadecimal value.
-A 32-bit numeral value is a numeral value between `0` and `2^32-1`.
+A _Boolean value_ is one of the Booleans `true` or `false`.
+An _arithmetic value_ is a (possibly negated) numeral, decimal or rational value.
+A _bit vector value_ (of bit width n) is a binary or hexadecimal value (of bit width n).
+An _$n$-bit numeral_, for $n ≥ 0$ is an numeral between $0$ and $2^n-1$.
 Binary values are considered to be in little endian form.
 
 Some of the following operators can be defined in terms of the other operators.
 For these operators, we provide the equivalent formulation.
 A signature defining these files can be found in [non-core-eval](#non-core-eval).
-Note however that the evaluation of these operators is handled by more efficient methods internally in the Ethos, that is, they are not treated as syntax sugar internally.
+Note however that the evaluation of these operators is handled by more efficient methods internally in the Ethos checker, that is, they are not treated as syntax sugar internally.
+
+<!--CT Added -->
+The semantics of each operator is described in terms of an evaluation function [ _ ] that takes a term containing applications of the operators and returns a term resulting from this evaluation.
+The function [ _ ] is defined below by specifying how applications of each operator _reduce_ to some (irreducible) term.
+
+<!--CT Added -->
+Ideally, the evaluation of an application of the form `(op t1 ... tn)`, where `op` is one of the operators below, results in a term from the set of values (Boolean, arithmetic, etc.).
+However, this is not always the case since several operators denote partial functions.
+For an input tuple `t1`, ..., `tn` outside of the definition domain of an operator `op`, the term `(op t1 ... tn)` does not evaluate, or rather, reduces to itself.
+
+<!--CT Added -->
+For brevity, the specification of the partial operators provided below is (intentionally) incomplete. It is understood that in the unspecified cases, the application `(op t1 ... tn)` reduces to itself. In other words, unless specified otherwise in the specifications below, [`(op t1 ... tn)`] = `(op t1 ... tn)`.
+
+In general, we refer to the term [`(op t1 ... tn)`], whether it reduces to a value or not, as the _result_ of applying `op` to the terms `t1`, ... `tn`.
 
 ### Core operators
 
+In the following, we list the core builtin operators of Ethos.
+
 - `(eo::is_eq t1 t2)`
-  - Returns `true` if `t1` is (syntactically) equal to `t2`, or `false` if `t1` and `t2` are distinct and ground. Otherwise, it does not evaluate.
 
-- `(eo::ite t1 t2 t3)`
-  - Returns `t2` if `t1` evaluates to `true`, `t3` if `t2` evaluates to `false`, and is not evaluated otherwise. Note that the branches of this term are only evaluated if they are the return term.
+  evaluates to `true` if `t1` and `t2` evaluate to the same term, and `false` if `t1` and `t2` evaluate to distinct, ground terms. (Otherwise, it evaluates to itself.)
+    More formally, 
+    $$[(\textsf{eo::is_eq}\ t_1\ t_2)] =
+    \begin{cases}
+     \textsf{true} & \text{if } [t_1], [t_2] \text{ are identical} \\
+     \textsf{false} & \text{if } [t_1], [t_2] \text{ are distinct and ground}
+    \end{cases}
+    $$
+   Recalling the note above, the specification of `eo::is_eq` implicitly says that $[(\textsf{eo::is_eq}\ t_1\ t_2)] = (\textsf{eo::is_eq}\ t_1\ t_2)$
+   when $[t_1]$ and $[t_2]$ are distinct but at least one of them is not ground.
+  <br><br>
+
+- `(eo::ite t t1 t2)`
+
+  evaluates to the value of `t1` if `t` evaluates to `true` and to the value of `t2` if `t` evaluates to `false`:
+
+    $$[(\textsf{eo::ite}\ t\ t_1\ t_2)] =
+    \begin{cases}
+     [t_1] & \text{if } [t] = \textsf{true} \\
+     [t_2] & \text{if } [t] = \textsf{false}
+    \end{cases}
+    $$
+  Note that the subterms `t1` and `t2` are only evaluated if they are the return term.
+  <br><br>
 
 - `(eo::requires t1 t2 t3)`
-  - Returns `t3` if `t1` is (syntactically) equal to `t2`, and is not evaluated otherwise.
-- `(eo::hash t1)`
-  - If `t1` is a ground term, this returns a numeral that is unique to `t1`.
-- `(eo::typeof t1)`
-  - If `t1` is a ground term, this returns the type of `t1`.
-- `(eo::nameof t1)`
-  - If `t1` is a ground constant or variable, this returns the name of `t1`, i.e. the string corresponding to the symbol it was declared with.
+
+  evaluates to the value of `t3` if `t1` and `t2` evaluate to the same term:
+
+    $$[(\textsf{eo::requires}\ t_1\ t_2\ t_3)] = [t_3] \quad \text{if } [t_1] = [t_2]$$
+
+- `(eo::hash t)`
+
+  If `t` evaluates to a ground term `u`, this evaluates to a numeral that is unique to `u`.
+  <br><br>
+
+- `(eo::typeof t)`
+
+  If `t` evaluates to a ground term `u`, this returns the type of `u`.
+  <br><br>
+
+- `(eo::nameof t)`
+
+  If `t` evaluates to a ground constant or variable `u`, this returns the name of `u`, i.e., the string corresponding to the symbol it was declared with.
+   <br><br>
+
 - `(eo::var t1 t2)`
-  - If `t1` is a string value and `t2` is ground type, this returns the variable whose name is `t1` and whose type is `t2`.
+
+  If `t1` evaluates to a string value and `t2` to a ground type, this evaluates to the variable whose name is [`t1`] and whose type is [`t2`].
+   <br><br>
+
 - `(eo::cmp t1 t2)`
-  - Equivalent to `(eo::is_neg (eo::add (eo::neg (eo::hash t1)) (eo::hash t2)))`. Note that this method corresponds to an arbitrary total order on terms.
+
+  is treated as `(eo::is_neg (eo::add (eo::neg (eo::hash t1)) (eo::hash t2)))`:
+  $$[(\textsf{eo::cmp}\ t_1\ t_2)] = [(\textsf{eo::is_neg}\ t)]$$
+  where $t$ is $(\textsf{eo::add}\ (\textsf{eo::neg}\ (\textsf{eo::hash}\ t_1))\ (\textsf{eo::hash}\ t_2))$.
+
+   Note that this method induces an arbitrary total order on values.
+   <br><br>
+
 - `(eo::is_z t)`
-  - Equivalent to `(eo::is_eq (eo::to_z t) t)`.
+
+  is treated as `(eo::is_eq (eo::to_z t) t)`:
+  $$[(\textsf{eo::is_z}\ t)] =[(\textsf{eo::is_eq}\ (\textsf{eo::to_z}\ t)\ t)]$$
+
 - `(eo::is_q t)`
-    - Equivalent to `(eo::is_eq (eo::to_q t) t)`. Note this returns false for decimal literals.
+
+   is treated as `(eo::is_eq (eo::to_q t) t)`:
+  $$[(\textsf{eo::is_q}\ t)] =[(\textsf{eo::is_eq}\ (\textsf{eo::to_q}\ t)\ t)]$$
+
+   Note this evaluates to `false` for decimal literals when `--no-normalize-dec` is enabled.
+   <br><br>
+
 - `(eo::is_bin t)`
-    - Equivalent to `(eo::is_eq (eo::to_bin (eo::len t) t) t)`. Note this returns false for hexadecimal literals.
+
+  is treated as `(eo::is_eq (eo::to_bin (eo::len t) t) t)`:
+  $$[(\textsf{eo::is_bin}\ t)] =[(\textsf{eo::is_eq}\ (\textsf{eo::to_bin}\ (\textsf{eo::len}\ t)\ t))]$$
+
+  Note this evaluates to `false` for hexadecimal literals when `--no-normalize-hex` is enabled.
+   <br><br>
+
 - `(eo::is_str t)`
-  - Equivalent to `(eo::is_eq (eo::to_str t) t)`.
+
+  is treated as `(eo::is_eq (eo::to_str t) t)`:
+  $$[(\textsf{eo::is_str}\ t)] =[(\textsf{eo::is_eq}\ (\textsf{eo::to_str}\ t)\ t)]$$
+
 - `(eo::is_bool t)`
-  - Equivalent to `(eo::or (eo::is_eq t true) (eo::is_eq t false))`.
+
+  is treated as `(eo::or (eo::is_eq t true) (eo::is_eq t false))`:
+  $$[(\textsf{eo::is_bool}\ t)] =[(\textsf{eo::is_eq}\ t\ \textsf{true})]$$
+
 - `(eo::is_var t)`
-  - Equivalent to `(eo::is_eq (eo::var (eo::nameof t) (eo::typeof t)) t)`.
+
+  is treated as `(eo::is_eq (eo::var (eo::nameof t) (eo::typeof t)) t)`:
+  $$[(\textsf{eo::is_var}\ t)] =[(\textsf{eo::is_eq}\ (\textsf{eo::var}\ (\textsf{eo::nameof}\ t)\ (\textsf{eo::typeof}\ t))\ t)]$$
 
 ### Boolean operators
 
 - `(eo::and t1 t2)`
-  - Boolean conjunction if `t1` and `t2` are Boolean values (`true` or `false`).
-  - Bitwise conjunction if `t1` and `t2` are bitwise values of the same category and bitwidth.
+  - Boolean conjunction if [`t1`] and [`t2`] are Boolean values (`true` or `false`).
+  - Bitwise conjunction if [`t1`] and [`t2`] are bit vector values of the same category and bit width.
+
 - `(eo::or t1 t2)`
-  - Boolean disjunction if `t1` and `t2` are Boolean values.
-  - Bitwise disjunction if `t1` and `t2` are bitwise values of the same category and bitwidth.
+  - Boolean disjunction if [`t1`] and [`t2`] are Boolean values.
+  - Bitwise disjunction if [`t1`] and [`t2`] are bit vector values of the same category and bit width.
 - `(eo::xor t1 t2)`
-  - Boolean xor if `t1` and `t2` are Boolean values.
-  - Bitwise xor if `t1` and `t2` are bitwise values of the same category and bitwidth.
+  - Boolean exclusive or if [`t1`] and [`t2`] are Boolean values.
+  - Bitwise exclusive or if [`t1`] and [`t2`] are bit vector values of the same category and bit width.
 - `(eo::not t1)`
-  - Boolean negation if `t1` is a Boolean value.
-  - Bitwise negation if `t1` is a bitwise value.
+  - Boolean negation if [`t1`] is a Boolean value.
+  - Bitwise negation if [`t1`] is a bit vector value.
 
 ### Arithmetic operators
 
 - `(eo::add t1 t2)`
-  - If `t1` and `t2` are arithmetic values of the same category, then this returns the addition of `t1` and `t2`.
-  - If `t1` and `t2` are bitwise values of the same category and bitwidth, this returns the binary value corresponding to their (unsigned) addition modulo their bitwidth.
+  - If [`t1`] and [`t2`] are arithmetic values of the same category, then this evaluates to the sum of [`t1`] and [`t2`].
+  - If [`t1`] and [`t2`] are bit vector values of the same category and bit width $n$, this evaluates to the binary value corresponding to their (unsigned) sum modulo $n$.
+
 - `(eo::mul t1 t2)`
-  - If `t1` and `t2` are arithmetic values of the same category, then this returns the multiplication of `t1` and `t2`.
-  - If `t1` and `t2` are bitwise values of the same category and bitwidth, this returns the binary value corresponding to their (unsigned) multiplication modulo their bitwidth.
+  - If [`t1`] and [`t2`] are arithmetic values of the same category, then this returns the product of [`t1`] and [`t2`].
+  - If [`t1`] and [`t2`] are bit vector values of the same category and bit width $n$, this returns the binary value corresponding to their (unsigned) product modulo $n$.
+
 - `(eo::neg t1)`
-  - If `t1` is a arithmetic value, this returns the arithmetic negation of `t1`.
-  - If `t1` is a binary value, this returns its (signed) arithmetic negation.
+  - If [`t1`] is a arithmetic value $a$, this returns the arithmetic negation of $a$.
+  - If [`t1`] is a bit vector value, this returns its (signed) arithmetic negation.
+
 - `(eo::qdiv t1 t2)`
-  - If `t1` and `t2` are values of the same category and `t2` is non-zero, then this returns the rational division of `t1` and `t2`.
+  - If [`t1`] and [`t2`] are arithmetic values of the same category and [`t2`] is non-zero, this returns the rational quotient of [`t1`] divided by [`t2`].
+
 - `(eo::zdiv t1 t2)`
-  - If `t1` and `t2` are numeral values and `t2` is non-zero, then this returns the integer division (floor) of `t1` and `t2`.
-  - If `t1` and `t2` are bitwise values of the same category and bitwidth, then this returns their (total, unsigned) division, where division by zero returns the max unsigned value.
+  - If [`t1`] and [`t2`] are numerals and [`t2`] is non-zero, this returns the integer quotient (floor) of [`t1`] divided by [`t2`].
+  - If [`t1`] and [`t2`] are bit vector values of the same syntactic category and bit width n, then this returns their (total, unsigned) quotient, with division by zero returning the max unsigned value of bit width n.
+
 - `(eo::zmod t1 t2)`
-  - If `t1` and `t2` are numeral values and `t2` is non-zero, then this returns the integer remainder of `t1` and `t2`.
-  - If `t1` and `t2` are bitwise values of the same category and bitwidth, then this returns their (total, unsigned) remainder, where remainder by zero returns `t1`.
+  - If [`t1`] and [`t2`] are numerals and [`t2`] is non-zero, then this returns the integer remainder of [`t1`] divided by [`t2`].
+  - If [`t1`] and [`t2`] are bit vector values of the same category and bit width, then this returns their (total, unsigned) remainder, where remainder by zero returns [`t1`].
+
 - `(eo::is_neg t1)`
-  - If `t1` is an arithmetic value, this returns `true` if `t1` is strictly negative and `false` otherwise. Otherwise, this operator is not evaluated.
+  - If [`t1`] is an arithmetic value, this returns `true` if [`t1`] is strictly negative and `false` otherwise.
+
 - `(eo::gt t1 t2)`
-  - Equivalent to `(eo::is_neg (eo::add (eo::neg t1) t2))`.
+
+  is treated as `(eo::is_neg (eo::add (eo::neg t1) t2))`.
 
 ### String operators
 
 - `(eo::len t1)`
-  - Binary length (bitwidth) if `t1` is a binary value.
-  - String length if `t1` is a string value.
+  - Binary length (bit width) if [`t1`] is a binary value.
+  - String length if [`t1`] is a string value.
+
 - `(eo::concat t1 t2)`
-  - The concatenation of bits if `t1` and `t2` are binary values.
-  - The concatenation of strings if `t1` and `t2` are string values.
+  - The bit vector concatenation of [`t1`] and [`t2`] if they are both binary values.
+  - The string concatenation of [`t1`] and [`t2`] if they are both are string values.
+
 - `(eo::extract t1 t2 t3)`
-  - If `t1` is a binary value and `t2` and `t3` are numeral values, this returns the binary value corresponding to the bits in `t1` from position `t2` through `t3` if `0<=t2`, or the empty binary value otherwise.
-  - If `t1` is a string value and `t2` and `t3` are numeral values, this returns the string value corresponding to the characters in `t1` from position `t2` through `t3` inclusive if `0<=t2`, or the empty string value otherwise.
+  - If [`t1`] is a binary value and [`t2`] and [`t3`] are numerals, this returns the binary value corresponding to the bits in [`t1`] from position [`t2`] through [`t3`] if [`t2`] is non-negative, or the empty bit vector otherwise.<!--CT this may need revising -->
+  - If [`t1`] is a string value and [`t2`] and [`t3`] are numerals, this returns the string value corresponding to the characters in [`t1`] from position [`t2`] through [`t3`] inclusive if [`t2`] is non-negative, or the empty string otherwise.
+
 - `(eo::find t1 t2)`
-  - If `t1` and `t2` are string values, this returns a numeral value corresponding to the first index (left to right) where `t2` occurs as a substring of `t1`, or the numeral value `-1` otherwise.
+  
+  If [`t1`] and [`t2`] are string values, this returns the numeral corresponding to the first index (left to right) where [`t2`] occurs as a substring of [`t1`], or the numeral value `-1` otherwise.
 
 ### Conversion operators
 
 - `(eo::to_z t1)`
-  - If `t1` is a numeral value, return `t1`.
-  - If `t1` is a rational value, return the numeral value corresponding to the floor of `t1`.
-  - If `t1` is a binary value, this returns the numeral value corresponding to `t1`.
-  - If `t1` is a string value of length one, this returns the code point of its character.
+  - If [`t1`] is an numeral value $n$, this evaluates to $n$.
+  - If [`t1`] is a rational value $r$, this evaluates to the numeral value corresponding to the floor of $r$ <!--CT this may need further clarification for the case when r is negative -->.
+  - If [`t1`] is a binary value $b$, this evaluates to the numeral value corresponding to $b$ <!--CT signed or unsigned? -->.
+  - If [`t1`] is a string value $s$ of length one, this evaluates the code point of $s$'s (only) character.
+
 - `(eo::to_q t1)`
-  - If `t1` is a rational value, return `t1`.
-  - If `t1` is a numeral value, this returns the (integral) rational value that is equivalent to `t1`.
+  - If [`t1`] is a rational value $r$, this evaluates to $r$.
+  - If [`t1`] is an numeral value $n$, this evaluates the (integral) rational value corresponding to $n$.
+
 - `(eo::to_bin t1 t2)`
-  - If `t1` is a 32-bit numeral value and `t2` is a binary value, this returns a binary value whose value is `t2` and whose bitwidth is `t1`.
-  - If `t1` is a 32-bit numeral value and `t2` is a numeral value, return the binary value whose value is `t2` (modulo `2^t1`) and whose bitwidth is `t1`.
+  - If [`t1`] is a 32-bit numeral $w_1$ and [`t2`] is a binary value $b$ of bit width $w_2$, this evaluates to the binary value $b$ of bit width $w_1$.<!--CT This does not seem well-defined. What happens when w_1 < w_2 or w_1 > w_2?  Zero-extension? Truncation?-->
+  - If [`t1`] is a 32-bit numeral $w$ and [`t2`] is a numeral $m$, this evaluates to the binary value of bit width $w$ corresponding to $(m \mod 2^w)$.
+
 - `(eo::to_str t1)`
-  - If `t1` is a string value, return `t1`.
-  - If `t1` is a numeral value specifying a code point from Unicode planes `0-2` (i.e. a numeral between `0` and `196607`), return the string of length one whose character has code point `t1`.
-  - If `t1` is a rational or binary value, return the string value corresponding to the result of printing `t1`. 
-  - If `t1` is a hexadecimal value, return the string value corresponding to the result of printing `t1`. This will use lowercase letters for digits greater than `9`.
-  - If `t1` is a decimal value, return the string value corresponding to the result of printing `t1` as a rational.
+  - If [`t1`] is a string value $s$, this evaluates to $s$.
+  - If [`t1`] is a numeral value $n$ specifying a code point from Unicode planes `0-2` (i.e., a numeral between `0` and `196607`), this evaluates to the string of length one whose character has code point $n$.
+  - If [`t1`] is a rational or bit vector value $v$, this evaluates to the string value `"`$v$`"`. Note that if $v$ is a hexadecimal, it will contain lowercase letters for digits greater than `9`.
+  - If [`t1`] is a decimal value $d$, this evaluates to [`(eo::to_str r)`] where `r` is the (normalized) rational corresponding to $d$.
 
 The Ethos eagerly evaluates ground applications of computational operators.
-In other words, the term `(eo::add 1 1)` is syntactically equivalent in all contexts to `2`.
+In other words, the term `(eo::mul (eo::add 1 1) 3)` is syntactically equivalent in all contexts to `6`.
+<!--CT Added -->
+ In contrast, expressions like `(eo::add (+ 1 1) 3)` and `(eo::mul (eo::add 1 1) a)` where `a` and `+` are user-declared symbols evaluate to themselves since neither `(+ 1 1)` nor `a` are values.
 
-Currently, apart from applications of `eo::ite`, all terms are evaluated bottom-up.
-This means that e.g. in the evaluation of `(eo::or A B)`, both `A` and `B` are always evaluated even if `A` evaluates to `true`.
+Currently, as it can be evinced of the description of [ _ ] above, term evaluation is eager and bottom-up with the only exception of `eo::ite`.
+This means that e.g. in the evaluation of `(eo::or t1 t2)`, both `t1` and `t2` are always evaluated even if `t1` evaluates to `true`.
+In contrast, in the evaluation of `(eo::ite t t1 t2)`, `t1` is evaluated only if `t` evaluates to `true` and `t2` is evaluated only if `t` evaluates to `false`.
 
-The Ethos supports extensions of `eo::and, eo::or, eo::xor, eo::add, eo::mul, eo::concat` to an arbitrary number of arguments `>=2`.
+The Ethos supports extensions of `eo::and, eo::or, eo::xor, eo::add, eo::mul, eo::concat` to an arbitrary number of arguments `>=2`, with the expected semantics.
 
 ### Computation Examples
 
+Here are a few examples of evaluations where the syntax `t1 == t2` means that [`t1`] is `t2`.
+
 ```smt
 (eo::and true false)        == false
 (eo::and #b1110 #b0110)     == #b0110
@@ -850,15 +962,15 @@ We say that a term is an `f`-list with children `t1 ... tn` if it is of the form
 - `(eo::nil f)`
   - If `f` is a right associative operator, return its nil terminator.
 - `(eo::cons f t1 t2)`
-  - If `t2` is an `f`-list, then this returns the term `(f t1 t2)`.
+  - If [`t2`] is an `f`-list, then this returns the term `(f t1 t2)`.
 - `(eo::list_len f t)`
   - If `t` is an `f`-list with children `t1 ... tn`, then this returns `n`.
 - `(eo::list_concat f t1 t2)`
-  - If `t1` is an `f`-list with children `t11 ... t1n` and `t2` is an `f`-list with children `t21 ... t2m`, this returns `(f t11 ... t1n t21 ... t2m)` if `n+m>0` and `nil` otherwise. Otherwise, this operator does not evaluate.
+  - If [`t1`] is an `f`-list with children `t11 ... t1n` and [`t2`] is an `f`-list with children `t21 ... t2m`, this returns `(f t11 ... t1n t21 ... t2m)` if `n+m>0` and `nil` otherwise. Otherwise, this operator does not evaluate.
 - `(eo::list_nth f t1 t2)`
-  - If `f` is a right associative operator with nil terminator with nil terminator `nil`, `t1` is `(f s0 ... s{n-1})`, and `t2` is a numeral value such that `0<=t2<n`, then this returns `s_{t2}`. Otherwise, this operator does not evaluate.
+  - If `f` is a right associative operator with nil terminator with nil terminator `nil`, [`t1`] is `(f s0 ... s{n-1})`, and [`t2`] is a numeral value such that `0<=t2<n`, then this returns `s_{t2}`. Otherwise, this operator does not evaluate.
 - `(eo::list_find f t1 t2)`
-  - If `f` is a right associative operator with nil terminator with nil terminator `nil` and `t1` is `(f s0 ... s{n-1})`, then this returns the smallest numeral value `i` such that `t2` is syntactically equal to `si`, or `-1` if no such `si` can be found. Otherwise, this operator does not evaluate.
+  - If `f` is a right associative operator with nil terminator with nil terminator `nil` and [`t1`] is `(f s0 ... s{n-1})`, then this returns the smallest numeral value `i` such that [`t2`] is syntactically equal to `si`, or `-1` if no such `si` can be found. Otherwise, this operator does not evaluate.
 
 ### List Computation Examples
 
@@ -935,10 +1047,10 @@ for the term `or` applied to arguments `a,b`.
 (define z () (concat x y) :type (BitVec 5))
 ```
 
-Above, we define a type declaration for `BitVec` that expects an integer (i.e. denoting the bitwidth) as an argument.
-Then, a type rule is given for bitvector concatenation `concat`, involves the result of invoking `eo::add` on the bitwidth of its two arguments.
+Above, we define a type declaration for `BitVec` that expects an integer (i.e. denoting the bit width) as an argument.
+Then, a type rule is given for bitvector concatenation `concat`, involves the result of invoking `eo::add` on the bit width of its two arguments.
 
-Since `eo::add` only evaluates on numeral values, this means that this type rule will only give the intended result when the bitwidth arguments to this function are concrete.
+Since `eo::add` only evaluates on numeral values, this means that this type rule will only give the intended result when the bit width arguments to this function are concrete.
 If on the other hand we defined:
 
 ```smt
@@ -986,7 +1098,7 @@ Its syntax is:
 ```
 
 In the following example,
-we declare bitvector-or (`bvor` in SMT-LIB) where its nil terminator is bitvector zero for the given bitwidth.
+we declare bitvector-or (`bvor` in SMT-LIB) where its nil terminator is bitvector zero for the given bit width.
 
 ```smt
 (declare-type Int ())
@@ -994,9 +1106,9 @@ we declare bitvector-or (`bvor` in SMT-LIB) where its nil terminator is bitvecto
 (declare-type BitVec (Int))
 (declare-consts <binary>
     (BitVec (eo::len eo::self)))              ; binary literals denote BitVec constants of their length
-(define bvzero ((m Int)) (eo::to_bin m 0))    ; returns the bitvector value zero for bitwidth m
+(define bvzero ((m Int)) (eo::to_bin m 0))    ; returns the bitvector value zero for bit width m
 
-(declare-parameterized-const bvor ((m Int))   ; bvor is parameterized by a bitwidth m
+(declare-parameterized-const bvor ((m Int))   ; bvor is parameterized by a bit width m
     (-> (BitVec m) (BitVec m) (BitVec m))
     :right-assoc-nil (bvzero m)               ; its nil terminator depends on m
 )
@@ -1039,7 +1151,7 @@ Examples of this are given in the following, assuming the declaration of `bvor`
 )
 ```
 
-Above, notice that `x` and `y` have concrete bitwidths and `z,w,u` have the free parameter `n` as their bitwidth.
+Above, notice that `x` and `y` have concrete bit widths and `z,w,u` have the free parameter `n` as their bit width.
 In the first term, `(bvor x y)` is type checked to `(BitVec m)[4/m]`.
 Since `4` is ground, we compute the nil terminator `(bvzero 4)`, which evaluates to `#b0000`.
 This is then used as the nil terminator, since `y` is not marked with `:list`.

From 0bb1952827bb9c1218300fabe68c5ca4e2444bf3 Mon Sep 17 00:00:00 2001
From: Cesare Tinelli <cesare-tinelli@uiowa.edu>
Date: Wed, 4 Sep 2024 17:31:32 -0500
Subject: [PATCH 08/12] more edits to incorporate old changes

---
 user_manual.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/user_manual.md b/user_manual.md
index cbf970ac..411e6ea5 100644
--- a/user_manual.md
+++ b/user_manual.md
@@ -576,8 +576,8 @@ We call _literal_ or _value_ any element of the seven syntactic categories above
 <!--CT Added. -->
 > __Note:__ Numerals include _negated_ literals such as `-1`, `-43`, and so on. Also, and in contrast to SMT-LIB version 2, rational literals can be specified directly using the syntax `5/11`, `2/4`, `0/1` and so on, and negative values can be provided as single literals, e.g., `-1`, `-10.5`, `-1/3` and so on, instead of more complex expressions such as `(- 1)`, `(- 10.5)`, and `(/ (- 1) 3)`.
 
-By default, decimal literals are treated by Ethos as syntax sugar for rational literals unless the option `--no-normalize-dec` is enabled.
-Similarly, hexadecimal literals are treated as syntax sugar for binary literals unless the option `--no-normalize-hex` is enabled.
+By default, decimal literals are treated by Ethos as syntax sugar for rational literals.
+Similarly, hexadecimal literals are treated as syntax sugar for binary literals.
 Rationals are normalized so that, e.g., `2/4` and `1/2` are syntactically equivalent after parsing.
 Similarly, decimals are normalized so that e.g. `1.300` is syntactically equivalent to `1.3` after parsing.
 Note this is independent of whether these decimal values are further normalized to rational values.
@@ -726,7 +726,7 @@ In the following, we list the core builtin operators of Ethos.
    is treated as `(eo::is_eq (eo::to_q t) t)`:
   $$[(\textsf{eo::is_q}\ t)] =[(\textsf{eo::is_eq}\ (\textsf{eo::to_q}\ t)\ t)]$$
 
-   Note this evaluates to `false` for decimal literals when `--no-normalize-dec` is enabled.
+   Note this evaluates to `false` for decimal literals.
    <br><br>
 
 - `(eo::is_bin t)`
@@ -734,7 +734,7 @@ In the following, we list the core builtin operators of Ethos.
   is treated as `(eo::is_eq (eo::to_bin (eo::len t) t) t)`:
   $$[(\textsf{eo::is_bin}\ t)] =[(\textsf{eo::is_eq}\ (\textsf{eo::to_bin}\ (\textsf{eo::len}\ t)\ t))]$$
 
-  Note this evaluates to `false` for hexadecimal literals when `--no-normalize-hex` is enabled.
+  Note this evaluates to `false` for hexadecimal literals.
    <br><br>
 
 - `(eo::is_str t)`
@@ -1834,7 +1834,7 @@ For example:
 
 Here, `normalize` is introduced as a program which recursively replaces all occurrences of division (over integer constants) with the resulting rational constant.
 This method can be used for handling solvers that interpret constant division as the construction of a rational constant.
-The above program will be invoked on all formulas occuring in `assert` commands in `"file.smt2"` and subsequently formulas in `assume` commands.
+The above program will be invoked on all formulas occurring in `assert` commands in `"file.smt2"` and subsequently formulas in `assume` commands.
 
 ## Oracles
 

From 398a108d7cd3be415f7e21ae493a4106820bae4a Mon Sep 17 00:00:00 2001
From: Cesare Tinelli <cesare-tinelli@uiowa.edu>
Date: Sun, 8 Sep 2024 01:00:31 -0500
Subject: [PATCH 09/12] Initial revision of Operators section

---
 user_manual.md | 557 +++++++++++++++++++++++++------------------------
 1 file changed, 289 insertions(+), 268 deletions(-)

diff --git a/user_manual.md b/user_manual.md
index b43caaa9..939aa3dc 100644
--- a/user_manual.md
+++ b/user_manual.md
@@ -459,7 +459,7 @@ the term `(f t1 ... tn)` is de-sugared based on whether each `t1 ... tn` is mark
 
 - The nil terminator is inserted at the tail of the function application unless `tn` is marked as `:list`,
 
-- If `ti` is marked as `:list` where `1<=i<n`, then `ti` is prepended to the overall application using a concatenation operation `eo::list_concat`. The semantics of this operator is provided later in [list-computation](#list-computation).
+- If `ti` is marked as `:list` where `1 <= i < n`, then `ti` is prepended to the overall application using a concatenation operation `eo::list_concat`. The semantics of this operator is provided later in [list-computation](#list-computation).
 
 In detail, the returned term from desugaring `(f t1 ... tn)` is constructed inductively.
 If `tn` is marked with `:list`, the returned term is initialized to `tn` and we process children `ti` from `i = n-1 ... 1`.
@@ -562,23 +562,24 @@ This option does not impact how binders are parsed in Eunoia files.
 The Eunoia language supports associating SMT-LIB version 3.0 syntactic categories with types. In detail, a syntax category is one of the following:
 
 - `<boolean>` denoting the category of _Boolean_ literals `true | false`,
-- `<numeral>` denoting the category of (integer) _numerals_ `-?<digit>+`,
+- `<numeral>` denoting the category of (integer) _numerals_ `-?<digit>+` where `<digit>` is `[0-9]`,
 - `<decimal>` denoting the category of _decimals_ `-?<digit>+.<digit>+`,
 - `<rational>` denoting the category of _rationals_ `-?<digit>+/<digit>+`,
-- `<binary>` denoting the category of _binary_ literals `#b<0|1>+`,
-- `<hexadecimal>` denoting the category of _hexadecimals_ `#x<hex-digit>+` where hexdigit is `[0-9] | [a-f] | [A-F]`,
-- `<string>` denoting the category of _strings_ literals `"<char>*"` <!--CT Added --> where `<char>` consists of the set of UTF-8 characters.
+- `<binary>` denoting the category of _binaries_ `#b[0-1]+`,
+- `<hexadecimal>` denoting the category of _hexadecimals_ `#x<hex-digit>+` where `<hex-digit>` is `[0-9] | [a-f] | [A-F]`,
+- `<string>` denoting the category of _strings_ literals `"<char>*"` <!--CT Added-->where `<char>` consists of the set of UTF-8 characters.
 
 <!--CT Added. -->
 We call _literal_ or _value_ any element of the seven syntactic categories above.
+We refer to collectively to binaries and hexadecimals as _bit vector values_ and to numerals, decimals and rationals as _arithmetic values_.
 
 <!--CT Added. -->
-> __Note:__ Numerals include _negated_ literals such as `-1`, `-43`, and so on. Also, and in contrast to SMT-LIB version 2, rational literals can be specified directly using the syntax `5/11`, `2/4`, `0/1` and so on, and negative values can be provided as single literals, e.g., `-1`, `-10.5`, `-1/3` and so on, instead of more complex expressions such as `(- 1)`, `(- 10.5)`, and `(/ (- 1) 3)`.
+> __Note:__ Numerals include _negated_ literals such as `-1`, `-43`, and so on. Also, and in contrast to SMT-LIB version 2, rational literals can be specified directly using the syntax `5/11`, `2/4`, `0/1` and so on, and negative values can be provided as single literals, e.g., `-1`, `-10.5`, `-1/3` and so on, instead of terms such as `(- 1)`, `(- 10.5)`, and `(/ (- 1) 3)`.
 
 By default, decimal literals are treated by Ethos as syntax sugar for rational literals.
 Similarly, hexadecimal literals are treated as syntax sugar for binary literals.
 Rationals are normalized so that, e.g., `2/4` and `1/2` are syntactically equivalent after parsing.
-Similarly, decimals are normalized so that e.g. `1.300` is syntactically equivalent to `1.3` after parsing.
+Similarly, decimals are normalized so that, e.g., `1.300` is syntactically equivalent to `1.3` after parsing.
 Note this is independent of whether these decimal values are further normalized to rational values.
 In other words, by default `1.300` is syntactically equivalent to the rational `13/10`.
 
@@ -612,9 +613,6 @@ The signature can now refer to arbitrary numerals in definitions, e.g. `7` in th
 
 <a name="computation"></a>
 
-## Computational Operators
-<a name="computation"></a>
-
 ## Computational Operators
 
 The Ethos has builtin support for computations over all syntactic categories of SMT-LIB version 3.0.
@@ -641,313 +639,334 @@ A signature defining these files can be found in [non-core-eval](#non-core-eval)
 Note however that the evaluation of these operators is handled by more efficient methods internally in the Ethos checker, that is, they are not treated as syntax sugar internally.
 
 <!--CT Added -->
-The semantics of each operator is described in terms of an evaluation function [ _ ] that takes a term containing applications of the operators and returns a term resulting from this evaluation.
-The function [ _ ] is defined below by specifying how applications of each operator _reduce_ to some (irreducible) term.
+The semantics of each operator is described in terms of an evaluation function $[ \_ ]$ that takes a term containing applications of the operators and returns a term resulting from this evaluation.
+The function $[ \_ ]$ is defined below by specifying how applications of each operator _reduce_ to some (irreducible) term.
+With one exception, the if-then-else operator `eo::ite`, term evaluation is bottom up, where the evaluation of an application of the form $(op\ t_1\ \cdots\ t_n)$ is defined in terms of the reduced terms $[t_1]$, ..., $[t_n]$.
 
 <!--CT Added -->
-Ideally, the evaluation of an application of the form `(op t1 ... tn)`, where `op` is one of the operators below, results in a term from the set of values (Boolean, arithmetic, etc.).
+Ideally, the evaluation of an application $(op\ t_1\ \cdots\ t_n)$ results in a term from the set of values (Boolean, arithmetic, etc.).
 However, this is not always the case since several operators denote partial functions.
-For an input tuple `t1`, ..., `tn` outside of the definition domain of an operator `op`, the term `(op t1 ... tn)` does not evaluate, or rather, reduces to itself.
+For an input tuple $t_1, \ldots, t_n$ where at least one of the input terms is outside of the definition domain of the operator $op$, the term $(op\ t_1\ \cdots\ t_n)$ reduces only partially,  to $(op\ [t_1] \cdots\ [t_n])$.
+In general, we refer to the term $[(op\ t_1\ \cdots\ t_n)]$, whether it is a value or not, as the _result_ of applying $op$ to the terms $t_1, \ldots, t_n$.
+<!--CT What happens if a term t contains undeclared symbols? Does that make t only partially reducible or does it raise an error at parse time?-->
 
 <!--CT Added -->
-For brevity, the specification of the partial operators provided below is (intentionally) incomplete. It is understood that in the unspecified cases, the application `(op t1 ... tn)` reduces to itself. In other words, unless specified otherwise in the specifications below, [`(op t1 ... tn)`] = `(op t1 ... tn)`.
-
-In general, we refer to the term [`(op t1 ... tn)`], whether it reduces to a value or not, as the _result_ of applying `op` to the terms `t1`, ... `tn`.
+Because of the bottom up evaluation, the specification of the partial operators provided below  assumes for convenience that the provided argument terms $r_1, \ldots, r_n$ __are already reduced__ with respect to $[\_]$, that is, $[r_i] = r_i$
+for all $i=1,\ldots,n$.
+The specification of each operator $op$ is (intentionally) incomplete. It is understood that in the unspecified cases, if any, $[(op\ r_1\ \cdots\ r_n)] = (op\ [t_1]\ \cdots\ [t_n]) = (op\ r_1\ \cdots\ r_n)$.
 
 ### Core operators
 
 In the following, we list the core builtin operators of Ethos.
 
-- `(eo::is_eq t1 t2)`
+- `(eo::is_eq r1 r2)`
 
-  evaluates to `true` if `t1` and `t2` evaluate to the same term, and `false` if `t1` and `t2` evaluate to distinct, ground terms. (Otherwise, it evaluates to itself.)
+  evaluates to `true` if `r1` and `r2` are the same term, and `false` if `r1` and `r2` are distinct, ground terms. (Otherwise, it evaluates to itself.)
     More formally, 
-    $$[(\textsf{eo::is_eq}\ t_1\ t_2)] =
+    $$[(\textsf{eo::is_eq}\ r_1\ r_2)] =
     \begin{cases}
-     \textsf{true} & \text{if } [t_1], [t_2] \text{ are identical} \\
-     \textsf{false} & \text{if } [t_1], [t_2] \text{ are distinct and ground}
+     \textsf{true} & \text{if } r_1 = r_2 \\
+     \textsf{false} & \text{if } r_1, r_2 \text{ are distinct and ground}
     \end{cases}
     $$
-   Recalling the note above, the specification of `eo::is_eq` implicitly says that $[(\textsf{eo::is_eq}\ t_1\ t_2)] = (\textsf{eo::is_eq}\ t_1\ t_2)$
-   when $[t_1]$ and $[t_2]$ are distinct but at least one of them is not ground.
+   Recalling the note above, the specification of `eo::is_eq` implicitly says that $[(\textsf{eo::is_eq}\ r_1\ r_2)] = (\textsf{eo::is_eq}\ r_1\ r_2)$
+   when $r_1$ and $r_2$ are distinct but at least one of them is not ground.
+
+   __Example:__ `(eo::is_eq 5 5)` evaluates to `true`, `(eo::is_eq 4 5)` and `(eo::is_eq true 5)` to `false`, and `(eo::is_eq 5 x)` to `(eo::is_eq 5 x)`.
   <br><br>
 
-- `(eo::ite t t1 t2)`
+- `(eo::ite r t1 t2)`
 
-  evaluates to the value of `t1` if `t` evaluates to `true` and to the value of `t2` if `t` evaluates to `false`:
+  evaluates to the value of `t1` if `r` is `true` and to the value of `t2` if `r` is `false`:
 
-    $$[(\textsf{eo::ite}\ t\ t_1\ t_2)] =
-    \begin{cases}
-     [t_1] & \text{if } [t] = \textsf{true} \\
-     [t_2] & \text{if } [t] = \textsf{false}
-    \end{cases}
     $$
-  Note that the subterms `t1` and `t2` are only evaluated if they are the return term.
+    \begin{array}{rcl}
+     [(\textsf{eo::ite}\ \textsf{true}\ t_1\ t_2)] & = & [t_1]  \\
+     [(\textsf{eo::ite}\ \textsf{false}\ t_1\ t_2)] & = & [t_2]  \\
+    \end{array}
+    $$
+  Note that int his operator (and this one only) the subterms `t1` and  `t2` are only evaluated if they are the return term.
   <br><br>
 
-- `(eo::requires t1 t2 t3)`
+- `(eo::requires r1 r2 r3)`
 
-  evaluates to the value of `t3` if `t1` and `t2` evaluate to the same term:
+  evaluates to `r3` if `r1` and `r2` are the same term:
 
-    $$[(\textsf{eo::requires}\ t_1\ t_2\ t_3)] = [t_3] \quad \text{if } [t_1] = [t_2]$$
+    $$[(\textsf{eo::requires}\ r\ r\ r_3)] = r_3$$
 
-- `(eo::hash t)`
+   __Example:__ `(eo::requires (eo::is_eq 5 5) true "ok")` evaluates to `"ok"` since `(eo::is_eq 5 5)` evaluates to `true`.
+  <br><br>
 
-  If `t` evaluates to a ground term `u`, this evaluates to a numeral that is unique to `u`.
+- `(eo::hash r)`
+
+  If `r` is ground, this evaluates to a numeral that is unique to `r`.
   <br><br>
 
-- `(eo::typeof t)`
+- `(eo::typeof r)`
 
-  If `t` evaluates to a ground term `u`, this returns the type of `u`.
+  If `r` is ground, this returns the type of `r` (based on the types declared for the constants in `r`).<!--CT what if r contains undeclared symbols?-->
   <br><br>
 
-- `(eo::nameof t)`
+- `(eo::nameof r)`
 
-  If `t` evaluates to a ground constant or variable `u`, this returns the name of `u`, i.e., the string corresponding to the symbol it was declared with.
+  If `r` is a ground constant or variable, this returns the name of `r`, i.e., the string corresponding to the symbol it was declared with.
+  
+   __Example:__ `(eo::nameof 125)` evaluates to `"125"` and `(eo::nameof x)` evaluates to `"x"`.
    <br><br>
 
-- `(eo::var t1 t2)`
+- `(eo::var r1 r2)`
 
-  If `t1` evaluates to a string value and `t2` to a ground type, this evaluates to the variable whose name is [`t1`] and whose type is [`t2`].
-   <br><br>
+  If `r1` is a string value and `r2` is a ground type, this evaluates to the (unique) variable with name `r1` and type is `r2`.
+
+  >__Note:__ If `(List Int)`, say, is a type, `(eo::nameof (eo::var "x" (List Int)))` evaluates to `"x"` and `(eo::typeof (eo::var "x" (List Int)))` to `(List Int)`.
+  <br>
 
-- `(eo::cmp t1 t2)`
+- `(eo::cmp r1 r2)`
 
-  is treated as `(eo::is_neg (eo::add (eo::neg (eo::hash t1)) (eo::hash t2)))`:
-  $$[(\textsf{eo::cmp}\ t_1\ t_2)] = [(\textsf{eo::is_neg}\ t)]$$
-  where $t$ is $(\textsf{eo::add}\ (\textsf{eo::neg}\ (\textsf{eo::hash}\ t_1))\ (\textsf{eo::hash}\ t_2))$.
+  is treated as `(eo::is_neg (eo::add (eo::neg (eo::hash r1)) (eo::hash r2)))`:
+  $$[(\textsf{eo::cmp}\ r_1\ r_2)] = [(\textsf{eo::is_neg}\ t)]$$
+  where $t$ is $(\textsf{eo::add}\ (\textsf{eo::neg}\ (\textsf{eo::hash}\ r_1))\ (\textsf{eo::hash}\ r_2))$.
 
-   Note that this method induces an arbitrary total order on values.
+   In words, `(eo::cmp r1 r2)` evaluates to `true` (resp., `false`) if `r_1` has a smaller (resp., greater) hash value than `r_2`. Note that this method induces a total order on all values based on the hashing function `eo::hash`.
    <br><br>
 
-- `(eo::is_z t)`
+- `(eo::is_z r)`
+
+  is treated as `(eo::is_eq (eo::to_z r) r)`:
+  $$[(\textsf{eo::is_z}\ r)] =[(\textsf{eo::is_eq}\ (\textsf{eo::to_z}\ r)\ r)]$$
+
+  In words, `(eo::is_z r)` evaluates to `true` (resp., `false`) if `r` is a numeral (resp., is a value other than a numeral).
+
+  __Example:__ `(eo::is_z 125)` and `(eo::is_z -125)` evaluate to `true`, `(eo::is_z 3.2)` to `false` and `(eo::is_z x)` to `(eo::is_z x)`.
+  <br><br>
 
-  is treated as `(eo::is_eq (eo::to_z t) t)`:
-  $$[(\textsf{eo::is_z}\ t)] =[(\textsf{eo::is_eq}\ (\textsf{eo::to_z}\ t)\ t)]$$
+- `(eo::is_q r)`
 
-- `(eo::is_q t)`
+   is treated as `(eo::is_eq (eo::to_q r) r)`:
+  $$[(\textsf{eo::is_q}\ r)] =[(\textsf{eo::is_eq}\ (\textsf{eo::to_q}\ r)\ r)]$$
 
-   is treated as `(eo::is_eq (eo::to_q t) t)`:
-  $$[(\textsf{eo::is_q}\ t)] =[(\textsf{eo::is_eq}\ (\textsf{eo::to_q}\ t)\ t)]$$
+  In words, `(eo::is_q r)` evaluates to `true` (resp., `false`) if `r` is a rational (resp., is a value other than a rational).
 
-   Note this evaluates to `false` for decimal literals.
+  Note that this evaluates to `false` for decimal literals.
    <br><br>
 
-- `(eo::is_bin t)`
+- `(eo::is_bin r)`
 
-  is treated as `(eo::is_eq (eo::to_bin (eo::len t) t) t)`:
+  is treated as `(eo::is_eq (eo::to_bin (eo::len r) r) r)`:
   $$[(\textsf{eo::is_bin}\ t)] =[(\textsf{eo::is_eq}\ (\textsf{eo::to_bin}\ (\textsf{eo::len}\ t)\ t))]$$
 
   Note this evaluates to `false` for hexadecimal literals.
    <br><br>
 
-- `(eo::is_str t)`
+- `(eo::is_str r)`
 
-  is treated as `(eo::is_eq (eo::to_str t) t)`:
-  $$[(\textsf{eo::is_str}\ t)] =[(\textsf{eo::is_eq}\ (\textsf{eo::to_str}\ t)\ t)]$$
+  is treated as `(eo::is_eq (eo::to_str r) r)`:
+  $$[(\textsf{eo::is_str}\ r)] =[(\textsf{eo::is_eq}\ (\textsf{eo::to_str}\ r)\ r)]$$
 
-- `(eo::is_bool t)`
+- `(eo::is_bool r)`
 
-  is treated as `(eo::or (eo::is_eq t true) (eo::is_eq t false))`:
-  $$[(\textsf{eo::is_bool}\ t)] =[(\textsf{eo::is_eq}\ t\ \textsf{true})]$$
+  is treated as `(eo::or (eo::is_eq r true) (eo::is_eq r false))`:
+  $$[(\textsf{eo::is_bool}\ r)] = (\textsf{eo::or}\ (\textsf{eo::is_eq}\ r\ \textsf{true})\ (\textsf{eo::is_eq}\ r\ \textsf{false}))$$
+  <!-- Is this really the case?  
+       Does (eo::is_bool x) (where x is a constant/variable) evaluate 
+       to (eo::or (eo::is_eq x true) (eo::is_eq x false)) ? 
+  -->
 
-- `(eo::is_var t)`
+- `(eo::is_var r)`
 
-  is treated as `(eo::is_eq (eo::var (eo::nameof t) (eo::typeof t)) t)`:
-  $$[(\textsf{eo::is_var}\ t)] =[(\textsf{eo::is_eq}\ (\textsf{eo::var}\ (\textsf{eo::nameof}\ t)\ (\textsf{eo::typeof}\ t))\ t)]$$
+  is treated as `(eo::is_eq (eo::var (eo::nameof r) (eo::typeof r)) r)`:
+  $$[(\textsf{eo::is_var}\ r)] =[(\textsf{eo::is_eq}\ (\textsf{eo::var}\ (\textsf{eo::nameof}\ r)\ (\textsf{eo::typeof}\ r))\ r)]$$
 
 ### Boolean operators
 
-- `(eo::and t1 t2)`
-  - Boolean conjunction if [`t1`] and [`t2`] are Boolean values (`true` or `false`).
-  - Bitwise conjunction if [`t1`] and [`t2`] are bit vector values of the same category and bit width.
+- `(eo::and r1 r2)`
+  - Boolean conjunction if `r1` and `r2` are booleans.
+  - Bitwise conjunction if `r1` and `r2` are bit vector values of the same category and bit width.
 
-- `(eo::or t1 t2)`
-  - Boolean disjunction if [`t1`] and [`t2`] are Boolean values.
-  - Bitwise disjunction if [`t1`] and [`t2`] are bit vector values of the same category and bit width.
-- `(eo::xor t1 t2)`
-  - Boolean exclusive or if [`t1`] and [`t2`] are Boolean values.
-  - Bitwise exclusive or if [`t1`] and [`t2`] are bit vector values of the same category and bit width.
-- `(eo::not t1)`
-  - Boolean negation if [`t1`] is a Boolean value.
-  - Bitwise negation if [`t1`] is a bit vector value.
+- `(eo::or r1 r2)`
+  - Boolean disjunction if `r1` and `r2` are booleans.
+  - Bitwise disjunction if `r1` and `r2` are bit vector values of the same category and bit width.
+- `(eo::xor r1 r2)`
+  - Boolean exclusive or if `r1` and `r2` are booleans.
+  - Bitwise exclusive or if `r1` and `r2` are bit vector values of the same category and bit width.
+- `(eo::not r1)`
+  - Boolean negation if `r1` is a boolean.
+  - Bitwise negation if `r1` is a bit vector value.
 
 ### Arithmetic operators
 
-- `(eo::add t1 t2)`
-  - If [`t1`] and [`t2`] are arithmetic values of the same category, then this evaluates to the sum of [`t1`] and [`t2`].
-  - If [`t1`] and [`t2`] are bit vector values of the same category and bit width $n$, this evaluates to the binary value corresponding to their (unsigned) sum modulo $n$.
+- `(eo::add r1 r2)`
+  - If `r1` and `r2` are arithmetic values of the same category, then this evaluates to the sum of `r1` and `r2`.
+  - If `r1` and `r2` are bit vector values of the same category and bit width $n$, this evaluates to the binary value corresponding to their (unsigned) sum modulo $n$.
 
-- `(eo::mul t1 t2)`
-  - If [`t1`] and [`t2`] are arithmetic values of the same category, then this returns the product of [`t1`] and [`t2`].
-  - If [`t1`] and [`t2`] are bit vector values of the same category and bit width $n$, this returns the binary value corresponding to their (unsigned) product modulo $n$.
+- `(eo::mul r1 r2)`
+  - If `r1` and `r2` are arithmetic values of the same category, then this returns the product of `r1` and `r2`.
+  - If `r1` and `r2` are bit vector values of the same category and bit width $n$, this returns the binary value corresponding to their (unsigned) product modulo $n$.
 
-- `(eo::neg t1)`
-  - If [`t1`] is a arithmetic value $a$, this returns the arithmetic negation of $a$.
-  - If [`t1`] is a bit vector value, this returns its (signed) arithmetic negation.
+- `(eo::neg r1)`
+  - If `r1` is a arithmetic value $a$, this returns the arithmetic negation of $a$.
+  - If `r1` is a bit vector value, this returns its (signed) arithmetic negation.
 
-- `(eo::qdiv t1 t2)`
-  - If [`t1`] and [`t2`] are arithmetic values of the same category and [`t2`] is non-zero, this returns the rational quotient of [`t1`] divided by [`t2`].
+- `(eo::qdiv r1 r2)`
+  - If `r1` and `r2` are arithmetic values of the same category and `r2` is non-zero, this returns the rational quotient of `r1` divided by `r2`.
 
-- `(eo::zdiv t1 t2)`
-  - If [`t1`] and [`t2`] are numerals and [`t2`] is non-zero, this returns the integer quotient (floor) of [`t1`] divided by [`t2`].
-  - If [`t1`] and [`t2`] are bit vector values of the same syntactic category and bit width n, then this returns their (total, unsigned) quotient, with division by zero returning the max unsigned value of bit width n.
+- `(eo::zdiv r1 r2)`
+  - If `r1` and `r2` are numerals and `r2` is non-zero, this returns the integer quotient (floor) of `r1` divided by `r2`.
+  - If `r1` and `r2` are bit vector values of the same syntactic category and bit width n, then this returns their (total, unsigned) quotient, with division by zero returning the max unsigned value of bit width n.
 
-- `(eo::zmod t1 t2)`
-  - If [`t1`] and [`t2`] are numerals and [`t2`] is non-zero, then this returns the integer remainder of [`t1`] divided by [`t2`].
-  - If [`t1`] and [`t2`] are bit vector values of the same category and bit width, then this returns their (total, unsigned) remainder, where remainder by zero returns [`t1`].
+- `(eo::zmod r1 r2)`
+  - If `r1` and `r2` are numerals and `r2` is non-zero, then this returns the integer remainder of `r1` divided by `r2`.
+  - If `r1` and `r2` are bit vector values of the same category and bit width, then this returns their (total, unsigned) remainder, where remainder by zero returns `r1`.
 
-- `(eo::is_neg t1)`
-  - If [`t1`] is an arithmetic value, this returns `true` if [`t1`] is strictly negative and `false` otherwise.
+- `(eo::is_neg r1)`
+  - If `r1` is an arithmetic value, this returns `true` if `r1` is strictly negative and `false` otherwise.
 
-- `(eo::gt t1 t2)`
+- `(eo::gt r1 r2)`
 
-  is treated as `(eo::is_neg (eo::add (eo::neg t1) t2))`.
+  is treated as `(eo::is_neg (eo::add (eo::neg r1) r2))`.
 
 ### String operators
 
-- `(eo::len t1)`
-  - Binary length (bit width) if [`t1`] is a binary value.
-  - String length if [`t1`] is a string value.
+- `(eo::len r1)`
+  - Binary length (bit width) if `r1` is a binary value.
+  - String length if `r1` is a string value.
 
-- `(eo::concat t1 t2)`
-  - The bit vector concatenation of [`t1`] and [`t2`] if they are both binary values.
-  - The string concatenation of [`t1`] and [`t2`] if they are both are string values.
+- `(eo::concat r1 r2)`
+  - The bit vector concatenation of `r1` and `r2` if they are both binary values.
+  - The string concatenation of `r1` and `r2` if they are both are string values.
 
-- `(eo::extract t1 t2 t3)`
-  - If [`t1`] is a binary value and [`t2`] and [`t3`] are numerals, this returns the binary value corresponding to the bits in [`t1`] from position [`t2`] through [`t3`] if [`t2`] is non-negative, or the empty bit vector otherwise.<!--CT this may need revising -->
-  - If [`t1`] is a string value and [`t2`] and [`t3`] are numerals, this returns the string value corresponding to the characters in [`t1`] from position [`t2`] through [`t3`] inclusive if [`t2`] is non-negative, or the empty string otherwise.
+- `(eo::extract r1 r2 t3)`
+  - If `r1` is a binary value and `r2` and `r3` are numerals, this returns the binary value corresponding to the bits in `r1` from position `r2` through `r3` if `r2` is non-negative, or the empty bit vector otherwise.<!--CT this may need revising -->
+  - If `r1` is a string value and `r2` and `r3` are numerals, this returns the string value corresponding to the characters in `r1` from position `r2` through `r3` inclusive if `r2` is non-negative, or the empty string otherwise.
 
-- `(eo::find t1 t2)`
+- `(eo::find r1 r2)`
   
-  If [`t1`] and [`t2`] are string values, this returns the numeral corresponding to the first index (left to right) where [`t2`] occurs as a substring of [`t1`], or the numeral value `-1` otherwise.
+  If `r1` and `r2` are string values, this returns the numeral corresponding to the first index (left to right) where `r2` occurs as a substring of `r1`, or the numeral value `-1` otherwise.
 
 ### Conversion operators
 
-- `(eo::to_z t1)`
-  - If [`t1`] is an numeral value $n$, this evaluates to $n$.
-  - If [`t1`] is a rational value $r$, this evaluates to the numeral value corresponding to the floor of $r$ <!--CT this may need further clarification for the case when r is negative -->.
-  - If [`t1`] is a binary value $b$, this evaluates to the numeral value corresponding to $b$ <!--CT signed or unsigned? -->.
-  - If [`t1`] is a string value $s$ of length one, this evaluates the code point of $s$'s (only) character.
+- `(eo::to_z r1)`
+  - If `r1` is an numeral value $n$, this evaluates to $n$.
+  - If `r1` is a rational value $r$, this evaluates to the numeral value corresponding to the floor of $r$ <!--CT this may need further clarification for the case when r is negative -->.
+  - If `r1` is a binary value $b$, this evaluates to the numeral value corresponding to $b$ <!--CT signed or unsigned? -->.
+  - If `r1` is a string value $s$ of length one, this evaluates the code point of $s$'s (only) character.
 
-- `(eo::to_q t1)`
-  - If [`t1`] is a rational value $r$, this evaluates to $r$.
-  - If [`t1`] is an numeral value $n$, this evaluates the (integral) rational value corresponding to $n$.
+- `(eo::to_q r1)`
+  - If `r1` is a rational value $r$, this evaluates to $r$.
+  - If `r1` is a numeral value $n$, this evaluates the (integral) rational value corresponding to $n$.
 
-- `(eo::to_bin t1 t2)`
-  - If [`t1`] is a 32-bit numeral $w_1$ and [`t2`] is a binary value $b$ of bit width $w_2$, this evaluates to the binary value $b$ of bit width $w_1$.<!--CT This does not seem well-defined. What happens when w_1 < w_2 or w_1 > w_2?  Zero-extension? Truncation?-->
-  - If [`t1`] is a 32-bit numeral $w$ and [`t2`] is a numeral $m$, this evaluates to the binary value of bit width $w$ corresponding to $(m \mod 2^w)$.
+- `(eo::to_bin r1 r2)`
+  - If `r1` is a 32-bit numeral $w_1$ and `r2` is a binary value $b$ of bit width $w_2$, this evaluates to the binary value $b$ of bit width $w_1$.<!--CT This does not seem well-defined. What happens when w_1 < w_2 or w_1 > w_2?  Zero-extension? Truncation?-->
+  - If `r1` is a 32-bit numeral $w$ and `r2` is a numeral $m$, this evaluates to the binary value of bit width $w$ corresponding to $(m \mod 2^w)$.
 
-- `(eo::to_str t1)`
-  - If [`t1`] is a string value $s$, this evaluates to $s$.
-  - If [`t1`] is a numeral value $n$ specifying a code point from Unicode planes `0-2` (i.e., a numeral between `0` and `196607`), this evaluates to the string of length one whose character has code point $n$.
-  - If [`t1`] is a rational or bit vector value $v$, this evaluates to the string value `"`$v$`"`. Note that if $v$ is a hexadecimal, it will contain lowercase letters for digits greater than `9`.
-  - If [`t1`] is a decimal value $d$, this evaluates to [`(eo::to_str r)`] where `r` is the (normalized) rational corresponding to $d$.
+- `(eo::to_str r1)`
+  - If `r1` is a string value $s$, this evaluates to $s$.
+  - If `r1` is a numeral value $n$ specifying a code point from Unicode planes `0-2` (i.e., a numeral between `0` and `196607`), this evaluates to the string of length one whose character has code point $n$.
+  - If `r1` is a rational or bit vector value $v$, this evaluates to the string value `"`$v$`"`. Note that if $v$ is a hexadecimal, it will contain lowercase letters for digits greater than `9`.
+  - If `r1` is a decimal value $d$, this evaluates to [`(eo::to_str r)`] where `r` is the (normalized) rational corresponding to $d$.
 
 The Ethos eagerly evaluates ground applications of computational operators.
 In other words, the term `(eo::mul (eo::add 1 1) 3)` is syntactically equivalent in all contexts to `6`.
 <!--CT Added -->
- In contrast, expressions like `(eo::add (+ 1 1) 3)` and `(eo::mul (eo::add 1 1) a)` where `a` and `+` are user-declared symbols evaluate to themselves since neither `(+ 1 1)` nor `a` are values.
+ In contrast, expressions like `(eo::add (+ 1 1) 3)` and `(eo::mul (eo::add 1 1) a)`, where `a` and `+` are user-declared symbols, evaluate to themselves since neither `(+ 1 1)` nor `a` are values.
 
-Currently, as it can be evinced of the description of [ _ ] above, term evaluation is eager and bottom-up with the only exception of `eo::ite`.
-This means that e.g. in the evaluation of `(eo::or t1 t2)`, both `t1` and `t2` are always evaluated even if `t1` evaluates to `true`.
-In contrast, in the evaluation of `(eo::ite t t1 t2)`, `t1` is evaluated only if `t` evaluates to `true` and `t2` is evaluated only if `t` evaluates to `false`.
-
-The Ethos supports extensions of `eo::and, eo::or, eo::xor, eo::add, eo::mul, eo::concat` to an arbitrary number of arguments `>=2`, with the expected semantics.
+The Ethos supports extensions of `eo::and, eo::or, eo::xor, eo::add, eo::mul, eo::concat` to an arbitrary number of arguments $ \geq 2$, with the expected semantics.
 
 ### Computation Examples
 
-Here are a few examples of evaluations where the syntax `t1 == t2` means that [`t1`] is `t2`.
-
-```smt
-(eo::and true false)        == false
-(eo::and #b1110 #b0110)     == #b0110
-(eo::or true false)         == true
-(eo::xor true true)         == false
-(eo::xor #b111 #b011)       == #b100
-(eo::not true)              == false
-(eo::not #b1010)            == #b0101
-(eo::add 1 1)               == 2
-(eo::add 1 1 1 0)           == 3
-(eo::add 1/2 1/3)           == 5/6
-(eo::add 2 1/3)             == (eo::add 2 1/3)  ; no mixed arithmetic
-(eo::add 2/1 1/3)           == 7/3
-(eo::add 2.0 1/3)           == (eo::add 2.0 1/3)  ; since no mixed arithmetic
-(eo::add 2.0 2.5)           == 4.5
-(eo::add #b01 #b01)         == #b10
-(eo::add #x1 #b0001)        == (eo::add #x1 #b0001)  ; since no mixed arithmetic
-(eo::mul 2 7)               == 14
-(eo::mul 2 2 7)             == 28
-(eo::mul 1/2 1/4)           == 1/8
-(eo::neg -15)               == 15
-(eo::qdiv 12 6)             == 3/1
-(eo::qdiv 7 2)              == 7/2
-(eo::qdiv 7/1 2/1)          == 7/2
-(eo::qdiv 7.0 2.0)          == 7/2
-(eo::qdiv 7 0)              == (eo::qdiv 7 0)  ; no division by zero
-(eo::zdiv 12 3)             == 4
-(eo::zdiv 7 2)              == 3
-(eo::is_neg 0)              == false
-(eo::is_neg -7/2)           == true
-(eo::len "abc")             == 3
-(eo::len """hi""")          == 4
-(eo::len "\u{AB0E}")        == 1
-(eo::len "\uA")             == 3
-(eo::len #b11100)           == 5
-(eo::concat "abc" "def")    == "abcdef"
-(eo::concat #b000 #b11)     == #b00011
-(eo::extract "abcdef" 0 1)  == "ab"
-(eo::extract "abcdef" -1 3) == ""
-(eo::extract "abcdef" 1 10) == "bcdef"
-(eo::extract #b11100 2 4)   == #b111
-(eo::extract #b11100 2 1)   == #b
-(eo::extract #b111000 1 10) == #b11100
-(eo::extract #b10 -1 2)     == #b
-(eo::find "abc" "bc")       == 1
-(eo::find "abc" "")         == 0
-(eo::find "abcdef" "g")     == -1
-(eo::to_z 3/2)              == 1
-(eo::to_z 45)               == 45
-(eo::to_z "A")              == 65
-(eo::to_z "1")              == 49
-(eo::to_z "451")            == (eo::to_z "451")  ; string is not length one
-(eo::to_z "")               == (eo::to_z "")  ; string is not length one
-(eo::to_z "\u{9876}")       == 9876
-(eo::to_q 6)                == 6/1
-(eo::to_bin 4 3)            == #b0011
-(eo::to_bin 4 #b1)          == #b0001
-(eo::to_bin 2 #b10101010)   == #b10
-(eo::to_str 65)             == "A"
-(eo::to_str 123)            == "{"
-(eo::to_str -1)             == (eo::to_str -1) ; since not a valid code point
-(eo::to_str 200000)         == (eo::to_str 200000) ; since not a valid code point
-(eo::to_str 1/2)            == "1/2"
-(eo::to_str #b101)          == "#b101"
+Here are a few examples of evaluations, where the syntax `t --> r` means that [`t`] is `r`.
+
+```smt
+(eo::and true false)         -->  false
+(eo::and #b1110 #b0110)      -->  #b0110
+(eo::or true false)          -->  true
+(eo::xor true true)          -->  false
+(eo::xor #b111 #b011)        -->  #b100
+(eo::not true)               -->  false
+(eo::not #b1010)             -->  #b0101
+(eo::add 1 1)                -->  2
+(eo::add 1 1 1 0)            -->  3
+(eo::add 1/2 1/3)            -->  5/6
+(eo::add 2 1/3)              -->  (eo::add 2 1/3)  ; no mixed arithmetic
+(eo::add 2/1 1/3)            -->  7/3
+(eo::add 2.0 1/3)            -->  (eo::add 2.0 1/3)  ; since no mixed arithmetic
+(eo::add 2.0 2.5)            -->  4.5
+(eo::add #b01 #b01)          -->  #b10
+(eo::add #x1 #b0001)         -->  (eo::add #x1 #b0001)  ; since no mixed arithmetic
+(eo::mul 2 7)                -->  14
+(eo::mul 2 2 7)              -->  28
+(eo::mul 1/2 1/4)            -->  1/8
+(eo::neg -15)                -->  15
+(eo::qdiv 12 6)              -->  3/1
+(eo::qdiv 7 2)               -->  7/2
+(eo::qdiv 7/1 2/1)           -->  7/2
+(eo::qdiv 7.0 2.0)           -->  7/2
+(eo::qdiv 7 0)               -->  (eo::qdiv 7 0)  ; no division by zero
+(eo::zdiv 12 3)              -->  4
+(eo::zdiv 7 2)               -->  3
+(eo::is_neg 0)               -->  false
+(eo::is_neg -7/2)            -->  true
+(eo::len "abc")              -->  3
+(eo::len """hi""")           -->  4
+(eo::len "\u{AB0E}")         -->  1
+(eo::len "\uA")              -->  3
+(eo::len #b11100)            -->  5
+(eo::concat "abc" "def")     -->  "abcdef"
+(eo::concat #b000 #b11)      -->  #b00011
+(eo::extract "abcdef" 0 1)   -->  "ab"
+(eo::extract "abcdef" -1 3)  -->  ""
+(eo::extract "abcdef" 1 10)  -->  "bcdef"
+(eo::extract #b11100 2 4)    -->  #b111
+(eo::extract #b11100 2 1)    -->  #b
+(eo::extract #b111000 1 10)  -->  #b11100
+(eo::extract #b10 -1 2)      -->  #b
+(eo::find "abc" "bc")        -->  1
+(eo::find "abc" "")          -->  0
+(eo::find "abcdef" "g")      -->  -1
+(eo::to_z 3/2)               -->  1
+(eo::to_z 45)                -->  45
+(eo::to_z "A")               -->  65
+(eo::to_z "1")               -->  49
+(eo::to_z "451")             -->  (eo::to_z "451")  ; string is not length one
+(eo::to_z "")                -->  (eo::to_z "")  ; string is not length one
+(eo::to_z "\u{9876}")        -->  9876
+(eo::to_q 6)                 -->  6/1
+(eo::to_bin 4 3)             -->  #b0011
+(eo::to_bin 4 #b1)           -->  #b0001
+(eo::to_bin 2 #b10101010)    -->  #b10
+(eo::to_str 65)              -->  "A"
+(eo::to_str 123)             -->  "{"
+(eo::to_str -1)              -->  (eo::to_str -1) ; since not a valid code point
+(eo::to_str 200000)          -->  (eo::to_str 200000) ; since not a valid code point
+(eo::to_str 1/2)             -->  "1/2"
+(eo::to_str #b101)           -->  "#b101"
 ```
 
 ### Core Computation Examples
 
-Note the following examples of core operators for the given signature
-
 ```smt
 (declare-type Int ())
 (declare-const x Int)
 (declare-const y Int)
 (declare-const a Bool)
-;;
-(eo::is_eq 0 1)                         == false
-(eo::is_eq x y)                         == false
-(eo::is_eq x x)                         == true
-(eo::requires x 0 true)                 == (eo::requires x 0 true)  ; x and 0 are not syntactically equal
-(eo::requires x x y)                    == y
-(eo::requires x x Int)                  == Int
-(eo::ite false x y)                     == y
-(eo::ite true Bool Int)                 == Bool
-(eo::ite a x x)                         == (eo::ite a x x)  ; a is not a value
-
-(eo::is_eq 2 (eo::add 1 1))             == true
-(eo::is_eq x (eo::requires x 0 x))      == false
-(eo::ite (eo::is_eq x 1) x y)           == y
+```
+
+Note the following examples of core operators for the signature above:
+
+```smt
+(eo::is_eq 0 1)                     -->  false
+(eo::is_eq x y)                     -->  false
+(eo::is_eq x x)                     -->  true
+(eo::requires x 0 true)             -->  (eo::requires x 0 true)  ; x and 0 are not syntactically equal
+(eo::requires x x y)                -->  y
+(eo::requires x x Int)              -->  Int
+(eo::ite false x y)                 -->  y
+(eo::ite true Bool Int)             -->  Bool
+(eo::ite a x x)                     -->  (eo::ite a x x)  ; a is not a value
+
+(eo::is_eq 2 (eo::add 1 1))         -->  true
+(eo::is_eq x (eo::requires x 0 x))  -->  false
+(eo::ite (eo::is_eq x 1) x y)       -->  y
 ```
 
 In the above, it is important to note that `eo::is_eq` is a check for syntactic equality after evaluation.
@@ -966,63 +985,65 @@ We say that a term is an `f`-list with children `t1 ... tn` if it is of the form
 - `(eo::nil f)`
   - If `f` is a right associative operator, return its nil terminator.
 - `(eo::cons f t1 t2)`
-  - If [`t2`] is an `f`-list, then this returns the term `(f t1 t2)`.
+  - If `r2` is an `f`-list, then this returns the term `(f t1 t2)`.
 - `(eo::list_len f t)`
   - If `t` is an `f`-list with children `t1 ... tn`, then this returns `n`.
 - `(eo::list_concat f t1 t2)`
-  - If [`t1`] is an `f`-list with children `t11 ... t1n` and [`t2`] is an `f`-list with children `t21 ... t2m`, this returns `(f t11 ... t1n t21 ... t2m)` if `n+m>0` and `nil` otherwise. Otherwise, this operator does not evaluate.
+  - If `r1` is an `f`-list with children `t11 ... t1n` and `r2` is an `f`-list with children `t21 ... t2m`, this returns `(f t11 ... t1n t21 ... t2m)` if `n+m>0` and `nil` otherwise. Otherwise, this operator does not evaluate.
 - `(eo::list_nth f t1 t2)`
-  - If `f` is a right associative operator with nil terminator with nil terminator `nil`, [`t1`] is `(f s0 ... s{n-1})`, and [`t2`] is a numeral value such that `0<=t2<n`, then this returns `s_{t2}`. Otherwise, this operator does not evaluate.
+  - If `f` is a right associative operator with nil terminator with nil terminator `nil`, `r1` is `(f s0 ... s{n-1})`, and `r2` is a numeral value such that `0<=t2<n`, then this returns `s_{t2}`. Otherwise, this operator does not evaluate.
 - `(eo::list_find f t1 t2)`
-  - If `f` is a right associative operator with nil terminator with nil terminator `nil` and [`t1`] is `(f s0 ... s{n-1})`, then this returns the smallest numeral value `i` such that [`t2`] is syntactically equal to `si`, or `-1` if no such `si` can be found. Otherwise, this operator does not evaluate.
+  - If `f` is a right associative operator with nil terminator with nil terminator `nil` and `r1` is `(f s0 ... s{n-1})`, then this returns the smallest numeral value `i` such that `r2` is syntactically equal to `si`, or `-1` if no such `si` can be found. Otherwise, this operator does not evaluate.
 
 ### List Computation Examples
 
-The terms on both sides of the given evaluation are written in their form prior to desugaring, where recall that e.g. `(or a)` after desugaring is `(or a false)` and `(or a b)` is `(or a (or b false))`.
-
 ```smt
 (declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
 (declare-const and (-> Bool Bool Bool) :right-assoc-nil true)
 (declare-const a Bool)
 (declare-const b Bool)
+```
+
+Given the signature above, the terms on both sides of the evaluation below are written in their form prior to desugaring, where recall that, e.g., `(or a)` after desugaring is `(or a false)` and `(or a b)` is `(or a (or b false))`.
+
+```smt
+(eo::nil or)  -->  false
+(eo::nil a)   -->  (eo::nil a)                ; since a is not an associative operator
+
+(eo::cons or a (or a b))         -->  (or a a b)
+(eo::cons or false (or a b))     -->  (or false a b)
+(eo::cons or (or a b) (or b))    -->  (or (or a b) b)
+(eo::cons or false false)        -->  (or false)
+(eo::cons or a b)                -->  (eo::cons or a b)                ; since b is not an or-list
+(eo::cons or a (or b))           -->  (or a b)
+(eo::cons and (or a b) (and b))  -->  (and (or a b) b)
+(eo::cons and true (and a))      -->  (and a)
+(eo::cons and (and a) true)      -->  (and (and a))
+
+(eo::list_len or (or a b))         -->  2
+(eo::list_len or (or (or a a) b))  -->  2
+(eo::list_len or false)            -->  0
+(eo::list_len or (and a b))        -->  (eo::list_len or (and a b))  ; since (and a b) is not an or-list
+
+(eo::list_concat or false false)           -->  false
+(eo::list_concat or (or a b) (or b))       -->  (or a b b)
+(eo::list_concat or (or (or a a)) (or b))  -->  (or (or a a) b)
+(eo::list_concat or false (or b))          -->  (or b)
+(eo::list_concat or (or a b b) false)      -->  (or a b b)
+(eo::list_concat or a (or b))              -->  (eo::list_concat or a (or b))         ; since a is not an or-list
+(eo::list_concat or (or a) b)              -->  (eo::list_concat or (or a) b)         ; since b is not an or-list
+(eo::list_concat or (or a) (or b))         -->  (or a b)
+(eo::list_concat or (and a b) false)       -->  (eo::list_concat or (and a b) false)  ; since (and a b) is not an or-list
+
+(eo::list_nth or (or a b a) 1)   -->  b
+(eo::list_nth or (or a) 0)       -->  a
+(eo::list_nth or false 0)        -->  (eo::list_nth or false 0)         ; since false has <=0 children
+(eo::list_nth or (or a b a) 3)   -->  (eo::list_nth or (or a b a) 3)    ; since (or a b a) has <=3 children
+(eo::list_nth or (and a b b) 0)  -->  (eo::list_nth or (and a b b) 0)   ; since (and a b b) is not an or-list
 
-(eo::nil or)                  == false
-(eo::nil a)                   == (eo::nil a)                ; since a is not an associative operator
-
-(eo::cons or a (or a b))            == (or a a b)
-(eo::cons or false (or a b))        == (or false a b)
-(eo::cons or (or a b) (or b))       == (or (or a b) b)
-(eo::cons or false false)           == (or false)
-(eo::cons or a b)                   == (eo::cons or a b)                ; since b is not an or-list
-(eo::cons or a (or b))              == (or a b)
-(eo::cons and (or a b) (and b))     == (and (or a b) b)
-(eo::cons and true (and a))         == (and a)
-(eo::cons and (and a) true)         == (and (and a))
-
-(eo::list_len or (or a b))          == 2
-(eo::list_len or (or (or a a) b))   == 2
-(eo::list_len or false)             == 0
-(eo::list_len or (and a b))         == (eo::list_len or (and a b))  ; since (and a b) is not an or-list
-
-(eo::list_concat or false false)            == false
-(eo::list_concat or (or a b) (or b))        == (or a b b)
-(eo::list_concat or (or (or a a)) (or b))   == (or (or a a) b)
-(eo::list_concat or false (or b))           == (or b)
-(eo::list_concat or (or a b b) false)       == (or a b b)
-(eo::list_concat or a (or b))               == (eo::list_concat or a (or b))         ; since a is not an or-list
-(eo::list_concat or (or a) b)               == (eo::list_concat or (or a) b)         ; since b is not an or-list
-(eo::list_concat or (or a) (or b))          == (or a b)
-(eo::list_concat or (and a b) false)        == (eo::list_concat or (and a b) false)  ; since (and a b) is not an or-list
-
-(eo::list_nth or (or a b a) 1)           == b
-(eo::list_nth or (or a) 0)               == a
-(eo::list_nth or false 0)                == (eo::list_nth or false 0)         ; since false has <=0 children
-(eo::list_nth or (or a b a) 3)           == (eo::list_nth or (or a b a) 3)    ; since (or a b a) has <=3 children
-(eo::list_nth or (and a b b) 0)          == (eo::list_nth or (and a b b) 0)   ; since (and a b b) is not an or-list
-
-(eo::list_find or (or a b a) b)          == 1
-(eo::list_find or (or a b a) true)       == -1
-(eo::list_find or (and a b b) a)         == (eo::find or (and a b b) a)      ; since (and a b b) is not an or-list
+(eo::list_find or (or a b a) b)     -->  1
+(eo::list_find or (or a b a) true)  -->  -1
+(eo::list_find or (and a b b) a)    -->  (eo::find or (and a b b) a)      ; since (and a b b) is not an or-list
 ```
 
 ### Nil terminator with additional arguments
@@ -1030,7 +1051,7 @@ The terms on both sides of the given evaluation are written in their form prior
 As we will introduce in [param-constants](#param-constants),
 `eo::nil` is overloaded to accept addition arguments beyond the operator.
 In particular, `(eo::nil or a b)` intuitively denotes the nil terminator
-for the term `or` applied to arguments `a,b`.
+for the term `or` applied to arguments `a` and `b`.
 
 ### Example: Type rule for BitVector concatenation
 
@@ -1202,17 +1223,17 @@ The following are examples of list operations when using parameterized constant
 (declare-const b (BitVec 4))
 (declare-const c (BitVec 5))
 
-(eo::nil bvor)                == (eo::nil bvor)     ; since we cannot infer the type of bvor
-(eo::nil bvor a)              == #b0000             ; since #b0000 is the nil terminator of (bvor a)
-(eo::nil bvor a c)            == (eo::nil bvor a c) ; since (bvor a c) is ill-typed
-(eo::nil (eo::_ bvor 4))      == #b0000
+(eo::nil bvor)                 -->  (eo::nil bvor)     ; since we cannot infer the type of bvor
+(eo::nil bvor a)               -->  #b0000             ; since #b0000 is the nil terminator of (bvor a)
+(eo::nil bvor a c)             -->  (eo::nil bvor a c) ; since (bvor a c) is ill-typed
+(eo::nil (eo::_ bvor 4))       -->  #b0000
 
-(eo::cons bvor a #b0000)            == (bvor a)
-(eo::cons bvor c #b0000)            == (eo::cons bvor c #b0000) ; since (bvor c #b0000) is ill-typed
-(eo::cons bvor a (bvor a b))        == (bvor a a b)
+(eo::cons bvor a #b0000)             -->  (bvor a)
+(eo::cons bvor c #b0000)            --> (eo::cons bvor c #b0000) ; since (bvor c #b0000) is ill-typed
+(eo::cons bvor a (bvor a b))        --> (bvor a a b)
 
-(eo::list_concat bvor #b0000 #b0000)       == #b0000
-(eo::list_concat bvor (bvor a b) (bvor b)) == (bvor a b b)
+(eo::list_concat bvor #b0000 #b0000)       --> #b0000
+(eo::list_concat bvor (bvor a b) (bvor b)) --> (bvor a b b)
 ```
 
 > __Note:__ If no free parameters are used in the nil terminator of a parameterized constant, then it is treated equivalent to if it were declared via an ordinary declare-const command, and a warning is issued.

From 058ec8ccc5e9ba54feeff57869932376769d00c1 Mon Sep 17 00:00:00 2001
From: Cesare Tinelli <cesare-tinelli@uiowa.edu>
Date: Sun, 8 Sep 2024 01:05:32 -0500
Subject: [PATCH 10/12] Update user_manual.md

---
 user_manual.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/user_manual.md b/user_manual.md
index 939aa3dc..2ed26d30 100644
--- a/user_manual.md
+++ b/user_manual.md
@@ -1961,7 +1961,7 @@ Their expected syntax is `<smtlib2-command>*`.
 As mentioned, the first two kinds of file inputs take into account options concerning the normalization of terms (e.g. `--normalize-num`), while signature files do not.
 When streaming input to Ethos, we assume the input is being given for a proof file.
 
-```smt
+```bnf
 ;;;
 <eo-command> ::=
     (assume <symbol> <term>) |

From d9bc96975058a75321b462e5eca72db45b57e9aa Mon Sep 17 00:00:00 2001
From: Cesare Tinelli <cesare-tinelli@uiowa.edu>
Date: Sun, 8 Sep 2024 13:03:53 -0500
Subject: [PATCH 11/12] Some more polishing and comments

---
 user_manual.md | 282 +++++++++++++++++++++++++------------------------
 1 file changed, 145 insertions(+), 137 deletions(-)

diff --git a/user_manual.md b/user_manual.md
index 2ed26d30..98361b06 100644
--- a/user_manual.md
+++ b/user_manual.md
@@ -94,14 +94,13 @@ For this purpose, the Eunoia language has the following builtin constants:
 - `Bool`, denoting the Boolean type,
 - `true` and `false`, denoting the two values of type `Bool`.
 
-> __Note:__ The core logic of the Ethos also uses several builtin types (e.g. `Proof` and `Quote`) which define the semantics of proof rules. These types are intentionally to exposed to the Eunoia user. Details on then can be found throughout this document. More details on the core logic of the Ethos will be available in a forthcoming publication.
+> __Note:__ The core logic of the Ethos also uses several builtin types (e.g. `Proof` and `Quote`) which define the semantics of proof rules. These types are intentionally not exposed to the Eunoia user. Details on then can be found throughout this document. More details on the core logic of the Ethos will be available in a forthcoming publication.
 
 In the following, we informally use the syntactic categories `<symbol>` to denote an SMT-LIB 3.0 symbol, `<term>` to denote an SMT-LIB term and `<type>` to denote a term whose type is `Type`. The syntactic category `<typed-param>` is defined, BNF-style, as `(<symbol> <type> <attr>*)`. It binds `<symbol>` as a fresh parameter of the given type and attributes (if provided).
 
-The following commands are supported for declaring and defining types and terms. The first set of commands are identical to those in SMT-LIB version 3.0:
+The following commands are supported for declaring and defining types and terms. The first set of commands are identical to those in the upcoming SMT-LIB version 3.0:
 
 - `(declare-const <symbol> <type> <attr>*)` declares a constant named `<symbol>` whose type is `<type>`. Can be given an optional list of attributes (see [attributes](#attributes)).
-<!-- Moved here because it is present in SMT-LIB 3 -->
 
 - `(declare-consts <lit-category> <type>)` declares the class of symbols denoted by the literal category to have the given type.
 
@@ -110,8 +109,9 @@ The following commands are supported for declaring and defining types and terms.
   `(declare-const <symbol> Type)` if `<type>*` is empty, and for
   `(declare-const <symbol> (-> <type>* Type))` otherwise.
 
-<!--CT Do we really need `define-type`? -->
+<!--CT Do w really need `define-type`? -->
 - `(define-type <symbol> (<type>*) <type>)` defines `<symbol>` to be a lambda term whose type is given by the argument and return types.
+
 - `(declare-datatype <symbol> <datatype-dec>)` defines a datatype `<symbol>`, along with its associated constructors, selectors, discriminators and updaters.
 
 - `(declare-datatypes (<sort-dec>^n) (<datatype-dec>^n))` defines a list of `n` datatypes for some `n>0`.
@@ -120,19 +120,19 @@ The following commands are supported for declaring and defining types and terms.
 
 - `(reset)` removes all declarations and definitions and resets the global scope. This command is similar in nature to its counterpart in SMT-LIB.
 
-The Eunoia language contains further commands for declaring symbols that are not standard SMT-LIB version 3.0:
+The Eunoia language contains further commands for declaring symbols that are not standard SMT-LIB 3.
 
 - `(define <symbol> (<typed-param>*) <term> <attr>*)`, defines `<symbol>` to be a lambda term whose arguments and body and given by the command, or the body if the argument list is empty. Note that in contrast to the SMT-LIB command `define-fun`, a return type is not provided. The provided attributes may instruct the checker to perform e.g. type checking on the given term see [type checking define](#tcdefine).
 
 - `(declare-parameterized-const <symbol> (<typed-param>*) <type> <attr>*)` declares a globally scoped variable named `<symbol>` whose type is `<type>`.
 
 > __Note:__ Variables are internally treated the same as constants by Ethos. However, they are provided as a separate category, e.g., for user signatures that wish to distinguish universally quantified variables from free constants. They also have a relationship with user-defined binders, see [binders](#binders), and can be accessed via the builtin operator `eo::var` (see [computation](#computation)).
-
+>
 > __Note:__ Symbol overloading is supported, see [overloading](#overloading).
 
 #### Example: Basic Declarations
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-const c Int)
 (declare-const f (-> Int Int Int))
@@ -140,7 +140,7 @@ The Eunoia language contains further commands for declaring symbols that are not
 (declare-const P (-> Int Bool))
 ```
 
-Since Ethos does not assume any builtin definitions of SMT-LIB theories, definitions of standard symbols in SMT-LIB theories(such as `Int`, `+`, etc.) must be provided in Eunoia signatures. In the above example, symbol `c` is declared to be a constant (0-ary) symbol of type `Int`. The symbol `f` is a function taking two integers and returning an integer.
+Since Ethos does not assume any builtin definitions of any theories, definitions of standard symbols in SMT-LIB theories (such as `Int`, `+`, etc.) must be provided in Eunoia signatures. In the above example, symbol `c` is declared to be a constant (0-ary) symbol of type `Int`. The symbol `f` is a function taking two integers and returning an integer.
 
 Observe that despite the use of different syntax in their declarations, the types of `f` and `g` in the above example are identical as `->` is a right-associative binary type constructor.
 
@@ -148,7 +148,7 @@ Observe that despite the use of different syntax in their declarations, the type
 
 #### Example: Basic Definitions
 
-```smt
+```clojure
 (declare-const not (-> Bool Bool))
 (define id ((x Bool)) x)
 (define notId ((x Int)) (not (id x)))
@@ -160,7 +160,7 @@ Since `define` commands are treated as (hygienic) macro definitions, in this exa
 Furthermore, `notId` is mapped to the lambda term `(lambda ((x Bool)) (not x))`.
 In other words, the following sequence of commands is equivalent to the one above after parsing:
 
-```smt
+```clojure
 (declare-const not (-> Bool Bool))
 (define id ((x Bool)) x)
 (define notId ((x Int)) (not x))
@@ -170,7 +170,7 @@ In other words, the following sequence of commands is equivalent to the one abov
 
 Eunoia supports the declaration of polymorphic types, that is, types depending on other types.
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-type Array (Type Type))
 (declare-const a (Array Int Bool))
@@ -185,7 +185,7 @@ In the above example, we declare and integer type constructor of kind `Type` and
 
 Note the following declarations generate terms of the same type:
 
-```smt
+```clojure
 (declare-type Array_v2 (Type Type))
 (declare-const Array_v3 (-> Type Type Type))
 ```
@@ -198,7 +198,7 @@ To type check terms, `define` statements can be annotated with `:type <term>`.
 This allows the user to eagerly check that a term has a particular type at the place where it is defined.
 In particular:
 
-```smt
+```clojure
 (declare-const not (-> Bool Bool))
 (define notTrue () (not true) :type Bool)
 ```
@@ -209,7 +209,7 @@ This indicates that the checker compare the type it computed for the term `(not
 
 The Eunoia language uses the SMT-LIB version 3.0 attributes `:var <symbol>` and `:implicit` in term annotations for naming arguments of functions and specifying they are implicit.
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-const eq (-> (! Type :var T) T T Bool))
 (define P ((x Int) (y Int)) (eq Int x y))
@@ -219,7 +219,7 @@ The above example declares a predicate symbol `eq` whose first argument is a typ
 
 In contrast, the example below declares a predicate `=` where the type of the arguments is implicit (this corresponds to the SMT-LIB standard definition of `=`). In the definition of `P`, the type of the arguments `Int` is not provided.
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-const = (-> (! Type :var T :implicit) T T Bool))
 (define P ((x Int) (y Int)) (= x y))
@@ -229,20 +229,20 @@ In general, an argument can be made implicit if its value can be inferred from t
 
 We call `T` in the above definitions a _parameter_. The free parameters of the return type of an expression should be contained in at least one non-implicit argument. In particular, the following declaration is malformed, since the return type of `f` cannot be inferred from its arguments:
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-const f (-> (! Type :var T :implicit) Int T))
 ```
 
 > __Note:__ Internally, `(! T :var t)` is syntax sugar for the type `(Quote t)` where `t` is a parameter of type `T` and `Quote` is a distinguished type of kind `(-> (! Type :var U) U Type)`. When type checking applications of functions of type `(-> (Quote t) S)`, the parameter `t` is bound to the argument the function is applied to.
-
+>
 > __Note:__ Internally, `(! T :implicit)` drops `T` from the list of arguments of the function type we are defining.
 
 ### The :requires annotation
 
 Arguments to functions can also be annotated with the attribute `:requires (<term> <term>)` to denote a equality condition that is required for applications of the term to type check.
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-const BitVec (-> (! Int :var w :requires ((eo::is_neg w) false)) Type))
 ```
@@ -252,7 +252,7 @@ The second annotation indicates that the term `(eo::is_neg w)` must evaluate to
 Symbol `eo::is_neg` denotes a builtin function that returns `true` if its argument is a negative numeral, and returns false otherwise (for details, see [computation](#computation)).
 <!-- This needs discussion, what is the input type of `eo::is_neg`? How can `eo::is_neg` accept a value of a user-defined type `Int` given that it is builtin?  -->
 
-> __Note:__ Internally, `(! T :requires (t s))` is syntax sugar for the type term `(eo::requires t s T)` where `eo::requires` is an operator that evaluates to its third argument if and only if its first two arguments are _computationally_ equivalent (details on this operator are given in [computation](#computation)).
+> __Note:__ Internally, `(! T :requires (t s))` is treated as the type term `(eo::requires t s T)` where `eo::requires` is an operator that evaluates to its third argument if and only if its first two arguments are _computationally_ equivalent (details on this operator are given in [computation](#computation)).
 Furthermore, the function type `(-> (eo::requires t s T) S)` is treated as `(-> T (eo::requires t s S))`. Ethos rewrites all types of the former form to the latter.
 
 <a name="opaque"></a>
@@ -263,7 +263,7 @@ The attribute `:opaque` can be used to denote that a distinguished argument to a
 In particular, functions with opaque arguments intuitively can be considered a _family_ of functions indexed by their opaque arguments.
 An example of this annotation is the following:
 
-```smt
+```clojure
 (declare-type Array (Type Type))
 (declare-const @array_diff
    (-> (! Type :var T :implicit) (! Type :var U :implicit)
@@ -289,7 +289,7 @@ Functions can have both opaque and ordinary arguments, where the opaque argument
 The concatenation of the expected arguments can be passed to the symbol in the order they are given.
 For example:
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-const @purify_fun (-> (! (-> Int Int) :opaque) Int Int))
 
@@ -328,7 +328,7 @@ A parameter may be marked with the following attribute:
 
 #### Right/Left associative
 
-```smt
+```clojure
 (declare-const or (-> Bool Bool Bool) :right-assoc)
 (define P ((x Bool) (y Bool) (z Bool)) (or x y z))
 (define Q ((x Bool) (y Bool)) (or x y))
@@ -341,7 +341,7 @@ The term `(or x)` is also not impacted by the annotation, and denotes the _parti
 
 Left associative can be defined analogously:
 
-```smt
+```clojure
 (declare-const and (-> Bool Bool Bool) :left-assoc)
 (define P ((x Bool) (y Bool) (z Bool)) (and x y z))
 ```
@@ -357,7 +357,7 @@ More generally, a constant declared with the `:right-associative` annotation mus
 
 Eunoia supports a variant of the aforementioned functionality where a (ground) nil terminator is provided.
 
-```smt
+```clojure
 (declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
 (define P ((x Bool) (y Bool) (z Bool)) (or x y z))
 (define Q ((x Bool) (y Bool)) (or x y))
@@ -375,7 +375,7 @@ and `(or x)` as `(or false x)`.
 The advantage of right or left associative operators with nil terminators is that the terms they specify are unambiguous, which is not the case for right or left associative operators without nil terminators.
 Consider the following example:
 
-```smt
+```clojure
 (declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
 (define P1 ((x Bool) (y Bool) (z Bool)) (or x (or y z)))
 (define P2 ((x Bool) (y Bool) (z Bool)) (or x y z))
@@ -391,7 +391,7 @@ In contrast, marking `or` with `:right-assoc-nil false` leads after desugaring t
 >
 > For instance, with
 >
-> ```smt
+> ```clojure
 > (declare-const + (-> Int Int Int) :right-assoc-nil 1)
 > ```
 >
@@ -404,7 +404,7 @@ The type for right and left associative operators with nil terminators is typica
 The nil terminator of a right associative operator may involve previously declared symbols in the signature.
 For example:
 
-```smt
+```clojure
 (declare-type RegLan ())
 (declare-const re.all RegLan)
 (declare-const re.inter (-> RegLan RegLan RegLan) :right-assoc-nil re.all)
@@ -418,7 +418,7 @@ However, when using `declare-const`, the nil terminator of an associative operat
 For example, say we wish to declare bitvector or (`bvor` in SMT-LIB), where its nil terminator is bitvector zero for the given bit width.
 A possible declaration is the following:
 
-```smt
+```clojure
 (declare-const bvor
     (-> (! Int :var m :implicit) (BitVec m) (BitVec m) (BitVec m))
     :right-assoc-nil ???
@@ -435,7 +435,7 @@ Parameters can be marked with the annotation `:list`.
 This includes those in function symbol declarations, as well as parameters to (e.g. `define`, `program`, `declare-rule`) commands.
 This annotation marks that the term should be treated as a list of arguments when it occurs as an argument of a right (left) associative operator with a nil element. Note the following example:
 
-```smt
+```clojure
 (declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
 (define P ((x Bool) (y Bool)) (or x y))
 (define Q ((x Bool) (y Bool :list)) (or x y))
@@ -468,7 +468,7 @@ For each term `ti` we process, the returned term `r` is updated to `(f ti r)` if
 if `ti` is marked with `:list`.
 Examples of this desugaring are given below.
 
-```smt
+```clojure
 (declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
 (define test ((x Bool) (y Bool) (z Bool :list) (w Bool :list))
     (and
@@ -486,7 +486,7 @@ In contrast, `(or x)` denotes the `or` whose children are `x` and `false`.
 
 #### Chainable
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-const and (-> Bool Bool Bool) :right-assoc)
 (declare-const >= (-> Int Int Bool) :chainable)
@@ -502,7 +502,7 @@ where the type of its chaining operator is `(-> S S S)`, and that operator has b
 
 #### Pairwise
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-const and (-> Bool Bool Bool) :right-assoc)
 (declare-const distinct (-> (! Type :var T :implicit) T T Bool)
@@ -520,7 +520,7 @@ and that operator has been marked as variadic via some attribute.
 
 #### Binder
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-type @List ())
 (declare-const @nil @List)
@@ -587,8 +587,9 @@ String values use the standard escape sequences as specified in SMT-LIB version
 The only other escape sequences are of the form `\u{dn ...d1}` for `1<=n<=5` and `\u d4 d3 d2 d1` for hexadecimal digits `d1...d5` where `d5` is in the range `[0-2]`.
 
 > __Note:__ Numeral, rational and decimal values are implemented by the arbitrary precision arithmetic library GMP. Binary and hexadecimal values are implemented as layer on top of numeral values that tracks a bit width. String values are implemented as a vector of unsigned integers whose maximum value is specified by SMT-LIB version 2.6, namely the character set corresponds to Unicode values 0 to 196607.
+>
 > __Note:__ Numeral, rational and decimal values are implemented by the arbitrary precision arithmetic library GMP. Binary and hexadecimal values are implemented as layer on top of numeral values that tracks a bit width. String values are implemented as a vector of unsigned integers whose maximum value is specified by SMT-LIB version 2.6, namely the character set corresponds to Unicode values 0 to 196607.
-
+>
 > __Note:__ Except for `<boolean>`, the literal categories above are not associated to any type by default. The user must decides what type to assign to each of them, with the command `declare-consts`. In contrast, the values of `<boolean>` have the predefined type `Bool`. In other words, `(declare-type Bool ())` and `(declare-consts <boolean> Bool)` are part of the builtin signature assumed by Ethos.
 
 <a name="declare-consts"></a>
@@ -597,7 +598,7 @@ The only other escape sequences are of the form `\u{dn ...d1}` for `1<=n<=5` and
 
 The following gives an example of how to define the class of numeral constants.
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-consts <numeral> Int)
 (define P ((x Int)) (> x 7))
@@ -606,9 +607,10 @@ The following gives an example of how to define the class of numeral constants.
 In the above example, the `declare-consts` command specifies that numerals (`1`, `2`, `3`, and so on) are constants of type `Int`.
 The signature can now refer to arbitrary numerals in definitions, e.g. `7` in the definition of `P`.
 
-> __Note:__ Internally, the command above only impacts the type rule assigned to numerals that are parsed. Furthermore, the Ethos internally distinguishes whether a term is a numeral value, independently of its type, for the purposes of computational operators (see [computation](#computation)).
-
+> __Note:__ Internally, the `declare-consts` command above only impacts the type rule assigned to numerals that are parsed. Furthermore, Ethos internally distinguishes whether a term is a numeral value, independently of its type, for the purposes of computational operators (see [computation](#computation)).
+>
 > __Note:__ For specifying literals whose type rule varies based on the content of the constant, the Eunoia language uses a distinguished variable `eo::self` which can be used in `declare-consts` definitions. For an example, see the type rule for SMT-LIB bit-vector constants, described later in [bv-literals](#bv-literals).
+>
 > __Note:__ For specifying literals whose type rule varies based on the content of the constant, the Eunoia language uses a distinguished variable `eo::self` which can be used in `declare-consts` definitions. For an example, see the type rule for SMT-LIB bit-vector constants, described later in [bv-literals](#bv-literals).
 
 <a name="computation"></a>
@@ -617,20 +619,18 @@ The signature can now refer to arbitrary numerals in definitions, e.g. `7` in th
 
 The Ethos has builtin support for computations over all syntactic categories of SMT-LIB version 3.0.
 We list the operators below, roughly categorized by domain.
-<!--CT Added -->
-Note that all the operators operate on _terms_, _regardless_ of the user-defined type
-assigned to those terms. The behavior of each operator is based only on the syntax of its input terms, not their types.
+<!--CT Added --> All the builtin operators operate on _terms_, _regardless_ of the user-defined type assigned to those terms. The behavior of each operator is based only on the syntax of its input terms, not their types.
 
 Some of the operators are overloaded, i.e., they can be applied to multiple syntactic categories, with different behavior for each category.
-For example, `eo::add` returns the result of adding two numerals or rationals, but also can be used to add binary values (integers modulo a given bit width).
+For example, `eo::add` returns the result of adding two numerals or two rationals, but also can be used to add two binary values (seen as integers modulo a given bit width).
 Similarly, `eo::concat` returns the result of concatenating two string values, but can also concatenate two binary values.
 We remark on the semantics in the following.
 
 In the following, we say a term is _ground_ if it contains no parameters as subterms.
-A _Boolean value_ is one of the Booleans `true` or `false`.
+Recall that a _boolean value_ is one of the Booleans `true` or `false`.
 An _arithmetic value_ is a (possibly negated) numeral, decimal or rational value.
-A _bit vector value_ (of bit width n) is a binary or hexadecimal value (of bit width n).
 An _$n$-bit numeral_, for $n ≥ 0$ is an numeral between $0$ and $2^n-1$.
+A _bit vector value_ (of bit width n) is a binary or hexadecimal value (of bit width n).
 Binary values are considered to be in little endian form.
 
 Some of the following operators can be defined in terms of the other operators.
@@ -639,21 +639,22 @@ A signature defining these files can be found in [non-core-eval](#non-core-eval)
 Note however that the evaluation of these operators is handled by more efficient methods internally in the Ethos checker, that is, they are not treated as syntax sugar internally.
 
 <!--CT Added -->
-The semantics of each operator is described in terms of an evaluation function $[ \_ ]$ that takes a term containing applications of the operators and returns a term resulting from this evaluation.
-The function $[ \_ ]$ is defined below by specifying how applications of each operator _reduce_ to some (irreducible) term.
-With one exception, the if-then-else operator `eo::ite`, term evaluation is bottom up, where the evaluation of an application of the form $(op\ t_1\ \cdots\ t_n)$ is defined in terms of the reduced terms $[t_1]$, ..., $[t_n]$.
+The semantics of each operator is described in terms of an evaluation function $[ \cdot ]$ that takes a term containing applications of the operators and returns a term resulting from this evaluation.
+The function $[ \cdot ]$ is defined below by specifying how applications of each operator _reduce_ to some (irreducible) term.
+With one exception, the if-then-else operator `eo::ite`, term evaluation is bottom up, where the evaluation of an application of the form $(op\ t_1\ \cdots\ t_n)$ is defined with respect to the reduced terms $[t_1]$, ..., $[t_n]$.
 
 <!--CT Added -->
 Ideally, the evaluation of an application $(op\ t_1\ \cdots\ t_n)$ results in a term from the set of values (Boolean, arithmetic, etc.).
 However, this is not always the case since several operators denote partial functions.
-For an input tuple $t_1, \ldots, t_n$ where at least one of the input terms is outside of the definition domain of the operator $op$, the term $(op\ t_1\ \cdots\ t_n)$ reduces only partially,  to $(op\ [t_1] \cdots\ [t_n])$.
-In general, we refer to the term $[(op\ t_1\ \cdots\ t_n)]$, whether it is a value or not, as the _result_ of applying $op$ to the terms $t_1, \ldots, t_n$.
+For input terms $t_1, \ldots, t_n$, with at least one of them outside the definition domain of the operator $op$, the term $(op\ t_1\ \cdots\ t_n)$ reduces to the _stuck_ term $(op\ [t_1] \cdots\ [t_n])$.
+In general, we refer to the term $[(op\ t_1\ \cdots\ t_n)]$, whether it is a value or a stuck term, as the _result_ of applying $op$ to the terms $t_1, \ldots, t_n$.
 <!--CT What happens if a term t contains undeclared symbols? Does that make t only partially reducible or does it raise an error at parse time?-->
 
 <!--CT Added -->
-Because of the bottom up evaluation, the specification of the partial operators provided below  assumes for convenience that the provided argument terms $r_1, \ldots, r_n$ __are already reduced__ with respect to $[\_]$, that is, $[r_i] = r_i$
-for all $i=1,\ldots,n$.
-The specification of each operator $op$ is (intentionally) incomplete. It is understood that in the unspecified cases, if any, $[(op\ r_1\ \cdots\ r_n)] = (op\ [t_1]\ \cdots\ [t_n]) = (op\ r_1\ \cdots\ r_n)$.
+> __Note:__ Because of the bottom up evaluation, the specification of the partial operators provided below  assumes for convenience that the provided argument terms $r_1, \ldots, r_n$ __are already reduced__ with respect to $[-]$, that is, $[r_i] = r_i$ for all $i=1,\ldots,n$. <!--CT This assumes that [_] is terminating.-->
+Moreover, the specification of each operator $op$ is (intentionally) incomplete. It is understood that in the unspecified cases, if any, $[(op\ r_1\ \cdots\ r_n)] = (op\ [r_1]\ \cdots\ [r_n]) = (op\ r_1\ \cdots\ r_n)$.
+
+<!--CT Used - instead of _ for operator names in latex because itd does not render properly on Github-->
 
 ### Core operators
 
@@ -662,17 +663,19 @@ In the following, we list the core builtin operators of Ethos.
 - `(eo::is_eq r1 r2)`
 
   evaluates to `true` if `r1` and `r2` are the same term, and `false` if `r1` and `r2` are distinct, ground terms. (Otherwise, it evaluates to itself.)
-    More formally, 
-    $$[(\textsf{eo::is_eq}\ r_1\ r_2)] =
+    More formally,
+
+    $$[(\textsf{eo::is-eq}\ r_1\ r_2)] =
     \begin{cases}
      \textsf{true} & \text{if } r_1 = r_2 \\
      \textsf{false} & \text{if } r_1, r_2 \text{ are distinct and ground}
     \end{cases}
     $$
-   Recalling the note above, the specification of `eo::is_eq` implicitly says that $[(\textsf{eo::is_eq}\ r_1\ r_2)] = (\textsf{eo::is_eq}\ r_1\ r_2)$
+
+   Recalling the note above, the specification of `eo::is_eq` implicitly says that $[(\textsf{eo::is-eq}\ r_1\ r_2)] = (\textsf{eo::is-eq}\ r_1\ r_2)$
    when $r_1$ and $r_2$ are distinct but at least one of them is not ground.
 
-   __Example:__ `(eo::is_eq 5 5)` evaluates to `true`, `(eo::is_eq 4 5)` and `(eo::is_eq true 5)` to `false`, and `(eo::is_eq 5 x)` to `(eo::is_eq 5 x)`.
+   __Example:__ `(eo::is_eq 5 5)` evaluates to `true`, `(eo::is_eq 4 5)` and `(eo::is_eq true 5)` evaluate to `false`, and `(eo::is_eq 5 x)` to itself.
   <br><br>
 
 - `(eo::ite r t1 t2)`
@@ -704,7 +707,7 @@ In the following, we list the core builtin operators of Ethos.
 
 - `(eo::typeof r)`
 
-  If `r` is ground, this returns the type of `r` (based on the types declared for the constants in `r`).<!--CT what if r contains undeclared symbols?-->
+  If `r` is ground, this returns the type of `r` (based on the types declared for the constants in `r`).<!--CT What if r contains undeclared symbols? Also, this assume a type preservation theorem where t and [t] have the same type for all t. -->
   <br><br>
 
 - `(eo::nameof r)`
@@ -723,72 +726,64 @@ In the following, we list the core builtin operators of Ethos.
 
 - `(eo::cmp r1 r2)`
 
-  is treated as `(eo::is_neg (eo::add (eo::neg (eo::hash r1)) (eo::hash r2)))`:
-  $$[(\textsf{eo::cmp}\ r_1\ r_2)] = [(\textsf{eo::is_neg}\ t)]$$
-  where $t$ is $(\textsf{eo::add}\ (\textsf{eo::neg}\ (\textsf{eo::hash}\ r_1))\ (\textsf{eo::hash}\ r_2))$.
-
-   In words, `(eo::cmp r1 r2)` evaluates to `true` (resp., `false`) if `r_1` has a smaller (resp., greater) hash value than `r_2`. Note that this method induces a total order on all values based on the hashing function `eo::hash`.
+  is treated as `(eo::is_neg (eo::add (eo::neg (eo::hash r1)) (eo::hash r2)))`, that is, it  evaluates to `true` (resp., `false`) if `r1` has a smaller (resp., greater) hash value than `r2`. Note that this method induces a total order on all values based on the hashing function `eo::hash`.
    <br><br>
 
 - `(eo::is_z r)`
 
-  is treated as `(eo::is_eq (eo::to_z r) r)`:
-  $$[(\textsf{eo::is_z}\ r)] =[(\textsf{eo::is_eq}\ (\textsf{eo::to_z}\ r)\ r)]$$
-
-  In words, `(eo::is_z r)` evaluates to `true` (resp., `false`) if `r` is a numeral (resp., is a value other than a numeral).
+  is treated as `(eo::is_eq (eo::to_z r) r)`, that is, it evaluates to `true` (resp., `false`) if `r` is a numeral (resp., is a value other than a numeral).
 
   __Example:__ `(eo::is_z 125)` and `(eo::is_z -125)` evaluate to `true`, `(eo::is_z 3.2)` to `false` and `(eo::is_z x)` to `(eo::is_z x)`.
   <br><br>
 
 - `(eo::is_q r)`
 
-   is treated as `(eo::is_eq (eo::to_q r) r)`:
-  $$[(\textsf{eo::is_q}\ r)] =[(\textsf{eo::is_eq}\ (\textsf{eo::to_q}\ r)\ r)]$$
-
-  In words, `(eo::is_q r)` evaluates to `true` (resp., `false`) if `r` is a rational (resp., is a value other than a rational).
-
+   is treated as `(eo::is_eq (eo::to_q r) r)`, that is, `(eo::is_q r)` evaluates to `true` (resp., `false`) if `r` is a rational (resp., is a value other than a rational).
   Note that this evaluates to `false` for decimal literals.
    <br><br>
 
 - `(eo::is_bin r)`
 
-  is treated as `(eo::is_eq (eo::to_bin (eo::len r) r) r)`:
-  $$[(\textsf{eo::is_bin}\ t)] =[(\textsf{eo::is_eq}\ (\textsf{eo::to_bin}\ (\textsf{eo::len}\ t)\ t))]$$
-
-  Note this evaluates to `false` for hexadecimal literals.
+  is treated as `(eo::is_eq (eo::to_bin (eo::len r) r) r)`.
+  Note that it evaluates to `false` for hexadecimal literals.
    <br><br>
 
 - `(eo::is_str r)`
 
-  is treated as `(eo::is_eq (eo::to_str r) r)`:
-  $$[(\textsf{eo::is_str}\ r)] =[(\textsf{eo::is_eq}\ (\textsf{eo::to_str}\ r)\ r)]$$
+  is treated as `(eo::is_eq (eo::to_str r) r)`, that is, it evaluates to `true` if converting `r` to a string produces `r` itself, and it evaluates to `false` otherwise.
+   <br><br>
 
 - `(eo::is_bool r)`
 
-  is treated as `(eo::or (eo::is_eq r true) (eo::is_eq r false))`:
-  $$[(\textsf{eo::is_bool}\ r)] = (\textsf{eo::or}\ (\textsf{eo::is_eq}\ r\ \textsf{true})\ (\textsf{eo::is_eq}\ r\ \textsf{false}))$$
-  <!-- Is this really the case?  
-       Does (eo::is_bool x) (where x is a constant/variable) evaluate 
-       to (eo::or (eo::is_eq x true) (eo::is_eq x false)) ? 
+  is treated as `(eo::or (eo::is_eq r true) (eo::is_eq r false))`.<!-- 
+   Is this really the case?  
+   Does (eo::is_bool x) (where x is a constant/variable) evaluate 
+   to (eo::or (eo::is_eq x true) (eo::is_eq x false)) ? 
   -->
+   <br><br>
 
 - `(eo::is_var r)`
 
-  is treated as `(eo::is_eq (eo::var (eo::nameof r) (eo::typeof r)) r)`:
-  $$[(\textsf{eo::is_var}\ r)] =[(\textsf{eo::is_eq}\ (\textsf{eo::var}\ (\textsf{eo::nameof}\ r)\ (\textsf{eo::typeof}\ r))\ r)]$$
+  is treated as `(eo::is_eq (eo::var (eo::nameof r) (eo::typeof r)) r)`, that is, it evaluates to `true` if constructing a variable with `r`'s name and type yields `r` itself.
+<!--CT what about the other case, doesn't it get stuck sometimes? Do we want that instead of `false` in those cases?-->
 
 ### Boolean operators
 
 - `(eo::and r1 r2)`
   - Boolean conjunction if `r1` and `r2` are booleans.
   - Bitwise conjunction if `r1` and `r2` are bit vector values of the same category and bit width.
+   <br><br>
 
 - `(eo::or r1 r2)`
   - Boolean disjunction if `r1` and `r2` are booleans.
   - Bitwise disjunction if `r1` and `r2` are bit vector values of the same category and bit width.
+   <br><br>
+
 - `(eo::xor r1 r2)`
   - Boolean exclusive or if `r1` and `r2` are booleans.
   - Bitwise exclusive or if `r1` and `r2` are bit vector values of the same category and bit width.
+   <br><br>
+
 - `(eo::not r1)`
   - Boolean negation if `r1` is a boolean.
   - Bitwise negation if `r1` is a bit vector value.
@@ -798,28 +793,35 @@ In the following, we list the core builtin operators of Ethos.
 - `(eo::add r1 r2)`
   - If `r1` and `r2` are arithmetic values of the same category, then this evaluates to the sum of `r1` and `r2`.
   - If `r1` and `r2` are bit vector values of the same category and bit width $n$, this evaluates to the binary value corresponding to their (unsigned) sum modulo $n$.
+   <br><br>
 
 - `(eo::mul r1 r2)`
   - If `r1` and `r2` are arithmetic values of the same category, then this returns the product of `r1` and `r2`.
   - If `r1` and `r2` are bit vector values of the same category and bit width $n$, this returns the binary value corresponding to their (unsigned) product modulo $n$.
+   <br><br>
 
 - `(eo::neg r1)`
   - If `r1` is a arithmetic value $a$, this returns the arithmetic negation of $a$.
   - If `r1` is a bit vector value, this returns its (signed) arithmetic negation.
+   <br><br>
 
 - `(eo::qdiv r1 r2)`
   - If `r1` and `r2` are arithmetic values of the same category and `r2` is non-zero, this returns the rational quotient of `r1` divided by `r2`.
+   <br><br>
 
 - `(eo::zdiv r1 r2)`
   - If `r1` and `r2` are numerals and `r2` is non-zero, this returns the integer quotient (floor) of `r1` divided by `r2`.
   - If `r1` and `r2` are bit vector values of the same syntactic category and bit width n, then this returns their (total, unsigned) quotient, with division by zero returning the max unsigned value of bit width n.
+   <br><br>
 
 - `(eo::zmod r1 r2)`
   - If `r1` and `r2` are numerals and `r2` is non-zero, then this returns the integer remainder of `r1` divided by `r2`.
   - If `r1` and `r2` are bit vector values of the same category and bit width, then this returns their (total, unsigned) remainder, where remainder by zero returns `r1`.
+   <br><br>
 
 - `(eo::is_neg r1)`
   - If `r1` is an arithmetic value, this returns `true` if `r1` is strictly negative and `false` otherwise.
+   <br><br>
 
 - `(eo::gt r1 r2)`
 
@@ -830,14 +832,17 @@ In the following, we list the core builtin operators of Ethos.
 - `(eo::len r1)`
   - Binary length (bit width) if `r1` is a binary value.
   - String length if `r1` is a string value.
+   <br><br>
 
 - `(eo::concat r1 r2)`
   - The bit vector concatenation of `r1` and `r2` if they are both binary values.
   - The string concatenation of `r1` and `r2` if they are both are string values.
+   <br><br>
 
 - `(eo::extract r1 r2 t3)`
   - If `r1` is a binary value and `r2` and `r3` are numerals, this returns the binary value corresponding to the bits in `r1` from position `r2` through `r3` if `r2` is non-negative, or the empty bit vector otherwise.<!--CT this may need revising -->
   - If `r1` is a string value and `r2` and `r3` are numerals, this returns the string value corresponding to the characters in `r1` from position `r2` through `r3` inclusive if `r2` is non-negative, or the empty string otherwise.
+   <br><br>
 
 - `(eo::find r1 r2)`
   
@@ -850,14 +855,17 @@ In the following, we list the core builtin operators of Ethos.
   - If `r1` is a rational value $r$, this evaluates to the numeral value corresponding to the floor of $r$ <!--CT this may need further clarification for the case when r is negative -->.
   - If `r1` is a binary value $b$, this evaluates to the numeral value corresponding to $b$ <!--CT signed or unsigned? -->.
   - If `r1` is a string value $s$ of length one, this evaluates the code point of $s$'s (only) character.
+   <br><br>
 
 - `(eo::to_q r1)`
   - If `r1` is a rational value $r$, this evaluates to $r$.
   - If `r1` is a numeral value $n$, this evaluates the (integral) rational value corresponding to $n$.
+   <br><br>
 
 - `(eo::to_bin r1 r2)`
   - If `r1` is a 32-bit numeral $w_1$ and `r2` is a binary value $b$ of bit width $w_2$, this evaluates to the binary value $b$ of bit width $w_1$.<!--CT This does not seem well-defined. What happens when w_1 < w_2 or w_1 > w_2?  Zero-extension? Truncation?-->
   - If `r1` is a 32-bit numeral $w$ and `r2` is a numeral $m$, this evaluates to the binary value of bit width $w$ corresponding to $(m \mod 2^w)$.
+   <br><br>
 
 - `(eo::to_str r1)`
   - If `r1` is a string value $s$, this evaluates to $s$.
@@ -876,7 +884,7 @@ The Ethos supports extensions of `eo::and, eo::or, eo::xor, eo::add, eo::mul, eo
 
 Here are a few examples of evaluations, where the syntax `t --> r` means that [`t`] is `r`.
 
-```smt
+```clojure
 (eo::and true false)         -->  false
 (eo::and #b1110 #b0110)      -->  #b0110
 (eo::or true false)          -->  true
@@ -944,7 +952,7 @@ Here are a few examples of evaluations, where the syntax `t --> r` means that [`
 
 ### Core Computation Examples
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-const x Int)
 (declare-const y Int)
@@ -953,7 +961,7 @@ Here are a few examples of evaluations, where the syntax `t --> r` means that [`
 
 Note the following examples of core operators for the signature above:
 
-```smt
+```clojure
 (eo::is_eq 0 1)                     -->  false
 (eo::is_eq x y)                     -->  false
 (eo::is_eq x x)                     -->  true
@@ -997,7 +1005,7 @@ We say that a term is an `f`-list with children `t1 ... tn` if it is of the form
 
 ### List Computation Examples
 
-```smt
+```clojure
 (declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
 (declare-const and (-> Bool Bool Bool) :right-assoc-nil true)
 (declare-const a Bool)
@@ -1006,7 +1014,7 @@ We say that a term is an `f`-list with children `t1 ... tn` if it is of the form
 
 Given the signature above, the terms on both sides of the evaluation below are written in their form prior to desugaring, where recall that, e.g., `(or a)` after desugaring is `(or a false)` and `(or a b)` is `(or a (or b false))`.
 
-```smt
+```clojure
 (eo::nil or)  -->  false
 (eo::nil a)   -->  (eo::nil a)                ; since a is not an associative operator
 
@@ -1055,7 +1063,7 @@ for the term `or` applied to arguments `a` and `b`.
 
 ### Example: Type rule for BitVector concatenation
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-consts <numeral> Int)
 (declare-type BitVec (Int))
@@ -1078,7 +1086,7 @@ Then, a type rule is given for bitvector concatenation `concat`, involves the re
 Since `eo::add` only evaluates on numeral values, this means that this type rule will only give the intended result when the bit width arguments to this function are concrete.
 If on the other hand we defined:
 
-```smt
+```clojure
 ...
 (declare-const a Int)
 (declare-const b Int)
@@ -1096,7 +1104,7 @@ This was not the case with `z` in the previous example, whose type prior to eval
 
 ### Example: Type rule for BitVector constants
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-consts <numeral> Int)
 (declare-type BitVec (Int))
@@ -1118,14 +1126,14 @@ Recall that in [assoc-nil](#assoc-nil), when using `declare-const` to define ass
 In this section, we introduce a new command `declare-parameterized-const` which overcomes this limitation.
 Its syntax is:
 
-```smt
+```clojure
 (declare-parameterized-const <symbol> (<typed-param>*) <type> > <attr>*)
 ```
 
 In the following example,
 we declare bitvector-or (`bvor` in SMT-LIB) where its nil terminator is bitvector zero for the given bit width.
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-consts <numeral>Int)                ; numeral literals denote Int constants
 (declare-type BitVec (Int))
@@ -1163,7 +1171,7 @@ Otherwise, the nil terminator is `nil[ v1 ... vm / u1 ... um]`.
 Constructing `(f t1 ... tn)` then proceeds inductively via the same procedure described in [assoc-nil](#assoc-nil).
 Examples of this are given in the following, assuming the declaration of `bvor` above.
 
-```smt
+```clojure
 (declare-const p (-> Bool Bool))
 (define test ((x (BitVec 4)) (y (BitVec 4)) (n Int) (z (BitVec n)) (w (BitVec n)) (u (BitVec n) :list))
     ...
@@ -1196,7 +1204,7 @@ Examples can be found at the end of this section.
 
 Consider again the term `(bvor z w)` from the previous example:
 
-```smt
+```clojure
 (define test ((n Int) (z (BitVec n)) (w (BitVec n)))
     (bvor z w)        ; (bvor z (bvor w (eo::nil bvor z w)))
 )
@@ -1218,7 +1226,7 @@ An example use case for this feature is directly refer to the nil terminator of
 
 The following are examples of list operations when using parameterized constant `bvor`:
 
-```smt
+```clojure
 (declare-const a (BitVec 4))
 (declare-const b (BitVec 4))
 (declare-const c (BitVec 5))
@@ -1245,7 +1253,7 @@ The following are examples of list operations when using parameterized constant
 The Ethos supports symbol overloading.
 For example, the following is accepted:
 
-```smt
+```clojure
 (declare-const - (-> Int Int))
 (declare-const - (-> Int Int Int))
 (declare-const - (-> Real Real Real))
@@ -1269,7 +1277,7 @@ For example, `(eo::as - (-> Int Int Int))` evaluates to the second declared symb
 
 The generic syntax for a `declare-rule` command accepted by `ethos` is:
 
-```smt
+```clojure
 (declare-rule <symbol> <keyword>? <sexpr>*)
 ```
 
@@ -1279,7 +1287,7 @@ All rules not marked with `:ethos` are not supported by the checker are unsuppor
 
 If the keyword is `:ethos`, then the expected syntax that follows is given below:
 
-```smt
+```clojure
 (declare-rule <symbol> :ethos (<typed-param>*) <assumption>? <premises>? <arguments>? <reqs>? :conclusion <term> <attr>*)
 where
 <assumption>   ::= :assumption <term>
@@ -1315,7 +1323,7 @@ A proof rule is only well defined if the free parameters of the requirements and
 
 ### Example rule: Reflexivity of equality
 
-```smt
+```clojure
 (declare-const = (-> (! Type :var T :implicit) T T Bool))
 (declare-rule refl ((T Type) (t T))
     :premises ()
@@ -1331,7 +1339,7 @@ Notice that the type `T` is a part of the parameter list and not explicitly prov
 
 ### Example rule: Symmetry of Equality
 
-```smt
+```clojure
 (declare-const = (-> (! Type :var T :implicit) T T Bool))
 (declare-rule symm ((T Type) (t T) (s T))
     :premises ((= t s))
@@ -1346,7 +1354,7 @@ In detail, an application of this proof rule for premise proof `(= a b)` for con
 
 A list of requirements can be given to a proof rule.
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-consts <numeral> Int)
 (declare-const >= (-> Int Int Bool))
@@ -1363,7 +1371,7 @@ It requires that the left hand side of this inequality `x` is a negative numeral
 
 A rule can take an arbitrary number of premises via the syntax `:premise-list <term><term>`. For example:
 
-```smt
+```clojure
 (declare-const and (-> Bool Bool Bool) :right-assoc-nil true)
 (declare-rule and-intro ((F Bool))
     :premise-list F and
@@ -1383,7 +1391,7 @@ Note that the type of functions provided as the second argument of `:premise-lis
 
 The Eunoia language provides the commands `assume` and `step` for defining proofs. Their syntax is given by:
 
-```smt
+```clojure
 (assume <symbol> <term>)
 (step <symbol> <term>? :rule <symbol> <premises>? <arguments>?)
 where
@@ -1393,7 +1401,7 @@ where
 
 ### Example proof: symmetry of equality
 
-```smt
+```clojure
 (declare-const = (-> (! Type :var T :implicit) T T Bool))
 (declare-rule symm ((T Type) (t T) (s T))
     :premises ((= t s))
@@ -1412,7 +1420,7 @@ The Eunoia language includes commands `assume-push` and `step-pop` with the same
 However, the former can be seen as introducing a local assumption that is consumed by the latter.
 We give an example of this in following.
 
-```smt
+```clojure
 (declare-const => (-> Bool Bool Bool))
 (declare-rule implies-intro ((F Bool) (G Bool))
   :assumption F
@@ -1439,7 +1447,7 @@ Notice that `@p1` is removed from scope after `@p3` is applied.
 
 Locally assumptions can be arbitrarily nested, for example the above can be extended to:
 
-```smt
+```clojure
 ...
 (assume-push @p0 true)
 (assume-push @p1 false)
@@ -1452,7 +1460,7 @@ Locally assumptions can be arbitrarily nested, for example the above can be exte
 
 Similar to `declare-rule`, the Ethos supports an extensible syntax for programs whose generic syntax is given by:
 
-```smt
+```clojure
 (program <symbol> <keyword>? <sexpr>*)
 ```
 
@@ -1464,7 +1472,7 @@ If the keyword is `:ethos`, then the expected syntax that follows is given below
 In particular, in the Ethos, a program is an ordered lists of rewrite rules.
 The syntax for this command is as follows.
 
-```smt
+```clojure
 (program <symbol> :ethos (<typed-param>*) (<type>*) <type> ((<term> <term>)+))
 ```
 
@@ -1479,9 +1487,9 @@ A (ground) term `(f s1 ... sn)` evaluates by finding the first term in the first
 If no such term can be found, then the application does not evaluate.
 
 > __Note:__ Terms in program bodies are not statically type checked. Evaluating a program may introduce non-well-typed terms if the program body is malformed.
-
+>
 > __Note:__ For each case `((f ti1 ... tin) ri)` in the program body, the free parameters in `ri` are required to be a subset of the free parameters in `(f ti1 ... tin)`. Otherwise, an error is thrown.
-
+>
 > __Note:__ If a case is provided `(si ri)` in the definition of program `f` where `si` is not an application of `f`, an error is thrown.
 Furthermore, if `si` contains any computational operators (i.e. those with `eo::` prefix), then an error is thrown.
 
@@ -1489,7 +1497,7 @@ Furthermore, if `si` contains any computational operators (i.e. those with `eo::
 
 The following program (recursively) computes whether a formula `l` is contained as the direct child of an application of `or`:
 
-```smt
+```clojure
 (declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
 (program contains
     ((l Bool) (x Bool) (xs Bool :list))
@@ -1519,7 +1527,7 @@ Computing the latter is significantly faster in practice in the Ethos.
 
 ### Example: Finding a child in an `or` term (incorrect version)
 
-```smt
+```clojure
 (declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
 (program contains
     ((l Bool) (x Bool) (xs Bool))
@@ -1539,7 +1547,7 @@ However, `(contains (or a b c) a)` does not evaluate in this example.
 
 ### Example: Finding a child in an `or` term (incorrect version 2)
 
-```smt
+```clojure
 (declare-const or (-> Bool Bool Bool) :right-assoc-nil false)
 (program contains
     ((l Bool) (x Bool :list) (xs Bool :list))
@@ -1559,7 +1567,7 @@ Thus, the third case of the program, `(contains (eo::list_concat or x xs) l)`, i
 
 ### Example: Substitution
 
-```smt
+```clojure
 (program substitute
   ((T Type) (U Type) (S Type) (x S) (y S) (f (-> T U)) (a T) (z U))
   (S S U) U
@@ -1584,7 +1592,7 @@ Hence when `t` is `(@array_diff A B)`, we fall into the third case of the method
 Alternatively, the following version of substitution `substitute-o` pattern matches on applications of `@array_diff` explicitly.
 Calling it with arguments `A`, `B`, and `(@array_diff A B)` would return `(@array_diff B B)`.
 
-```smt
+```clojure
 (program substitute-o
   ((T Type) (U Type) (S Type) (x S) (y S) (a (Array T U)) (b (Array T U)) (z U))
   (S S U) U
@@ -1599,7 +1607,7 @@ Calling it with arguments `A`, `B`, and `(@array_diff A B)` would return `(@arra
 
 ### Example: Term evaluator
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-consts <numeral> Int)
 (declare-const = (-> (! Type :var T :implicit) T T Bool))
@@ -1626,7 +1634,7 @@ The above example recursively evaluates arithmetic terms and predicates accordin
 
 ### Example: A computational type rule
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-type Real ())
 (program arith.typeunion ()
@@ -1649,7 +1657,7 @@ The return type of `+` invokes this side condition, which conceptually is implem
 
 ### Example: Conversion to DIMACS
 
-```smt
+```clojure
 (declare-type String ())
 (declare-consts <string> String)
 (declare-const not (-> Bool Bool))
@@ -1686,7 +1694,7 @@ The above program `to_dimacs` converts an SMT formula into DIMACS form, where `e
 
 The Ethos supports an operator `eo::match` for performing pattern matching on a target term. The syntax of this term is:
 
-```smt
+```clojure
 (eo::match (<typed-param>*) <term> ((<term> <term>)*))
 ```
 
@@ -1695,12 +1703,12 @@ The term `(eo::match (...) t ((s1 r1) ... (sn rn)))` finds the first term `si` i
 > __Note:__  Match terms require the free parameters of `ri` are a subset of the provided parameter list.
 In other words, all patterns must only involve parameters that are locally bound as the first argument of the match term.
 Also, similar to programs, the free parameters of `ri` that occur in the parameter list must be a subset of `si`, or else an error is thrown.
-
+>
 > __Note:__ Like programs, match terms are not statically type checked.
 
 ### Examples of legal and illegal match terms
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-const F Bool)
 (declare-const a Int)
@@ -1740,7 +1748,7 @@ Also, similar to programs, the free parameters of `ri` that occur in the paramet
 
 ### Example: Proof rule for symmetry of (dis)equality
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-const = (-> (! Type :var T :implicit) T T Bool))
 (declare-const not (-> Bool Bool))
@@ -1761,7 +1769,7 @@ It matches the given premise `F` with either `(= t1 t2)` or `(not (= t1 t2))` an
 
 Internally, the semantics of `eo::match` can be seen as an (inlined) program applied to its head, such that the above example is equivalent to:
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-const = (-> (! Type :var T :implicit) T T Bool))
 (declare-const not (-> Bool Bool))
@@ -1784,7 +1792,7 @@ In more general cases, if the body of the match term contains free variables, th
 
 ### Example: Proof rule for transitivity of equality with a premise list
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-const = (-> (! Type :var T :implicit) T T Bool))
 (declare-const and (-> Bool Bool Bool) :left-assoc)
@@ -1831,7 +1839,7 @@ If ethos has read a reference file, then for each command of the form `(assume <
 If it does not, then an error is thrown indicating that the proof is assuming a formula that is not a part of the original input.
 
 > __Note:__ Only one reference command can be executed for each run of ethos.
-
+>
 > __Note:__ Incremental `*.smt2` inputs are not supported as reference files in the current version of ethos.
 
 ### Validation up to Normalization
@@ -1842,7 +1850,7 @@ For this reason, ethos additionally supports providing an optional normalization
 
 For example:
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-type Real ())
 (declare-const / (-> Int Int Real))
@@ -1869,7 +1877,7 @@ The syntax and semantics of such functions are described in this [paper](https:/
 
 In particular, the Ethos supports the command:
 
-```smt
+```clojure
 (declare-oracle-fun <symbol> (<type>*) <type> <symbol>)
 ```
 
@@ -1879,7 +1887,7 @@ Ground applications of oracle functions are eagerly evaluated by invoking the bi
 
 ### Example: Oracle isPrime
 
-```smt
+```clojure
 (declare-type Int ())
 (declare-consts <numeral> Int)
 (declare-const = (-> (! Type :var T :implicit) T T Bool))
@@ -2033,7 +2041,7 @@ When streaming input to Ethos, we assume the input is being given for a proof fi
 
 The following signature can be used to define operators that are not required to be supported as core evaluation operators.
 
-```smt
+```clojure
 ; Returns true if x is a numeral literal.
 (define eo::is_z ((T Type :implicit) (x T))
   (eo::is_eq (eo::to_z x) x))
@@ -2076,7 +2084,7 @@ This section overviews the semantics of proofs in the Eunoia language.
 Proof checking can be seen as a special instance of type checking terms involving the `Proof` and `Quote` types.
 The type system of the Ethos can be summarized as follows, where `t : S` are assumed axioms for all atomic terms `t` of type `S`:
 
-```smt
+```clojure
 f : (-> (Quote u) S)  t : T
 ---------------------------- if u * sigma = t
 (f t) : S * sigma
@@ -2093,7 +2101,7 @@ Note that Ethos additionally requires that all well-typed terms have a type that
 
 The command:
 
-```smt
+```clojure
 (declare-rule s ((v1 T1) ... (vi Ti)) 
     :premises (p1 ... pn) 
     :args (t1 ... tm) 
@@ -2103,7 +2111,7 @@ The command:
 
 can be seen as syntax sugar for:
 
-```smt
+```clojure
 (declare-const s
     (-> (! T1 :var v1 :implicit) ... (! Ti :var vi :implicit)
         (Proof p1) ... (Proof pn)
@@ -2114,25 +2122,25 @@ can be seen as syntax sugar for:
 
 The command:
 
-```smt
+```clojure
 (assume s f)
 ```
 
 can be seen as syntax sugar for:
 
-```smt
+```clojure
 (declare-const s (Proof f))
 ```
 
 The command:
 
-```smt
+```clojure
 (step s f :rule r :premises (p1 ... pn) :args (t1 ... tm))
 ```
 
 can be seen as syntax sugar for:
 
-```smt
+```clojure
 (define s () (r p1 ... pn t1 ... tm) :type (Proof f))
 ```
 

From b5f78104b4427729f415f7a864393c1fa91147a5 Mon Sep 17 00:00:00 2001
From: Cesare Tinelli <cesare-tinelli@uiowa.edu>
Date: Sun, 8 Sep 2024 13:05:05 -0500
Subject: [PATCH 12/12] Delete .DS_Store

---
 .DS_Store | Bin 8196 -> 0 bytes
 1 file changed, 0 insertions(+), 0 deletions(-)
 delete mode 100644 .DS_Store

diff --git a/.DS_Store b/.DS_Store
deleted file mode 100644
index e9378fd5e1f00250b64b7597856e410349f09352..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 8196
zcmeHMJ#Q016r6QzY$=T^6j5!1=#WB<l#Av3f>2U`ohXU0b5>&4Ttx#y)JWt9(9lrv
z15!|>;zQy`P|yGc%-dbtyLUdQAV|EGcIUG1y_?aTb?fH<FumE{Ca?jZ!ztKZ=dxl*
zTxMl7!j2^x)?;+AxjW3qlS-y;r~~SNI-m}y1M0xP;sDQV8J(JQ-$!*-2h@T8(gArt
zSWdw#VByidI=HwNfY{`=8@%qy1<?k~0u~+_;V{0G=u1s#F^n(gz72U<z`~<1hY8Jx
z3Ct#RD8{k#{??_#WFB=@2h@S81D0D&+{6KnFiraRYdf#w*f{U^2cvwzz0TX-*NYq5
z=i6y~@0an(Vf5R;^$V7wJ?F(CW*8*wxbmf%5o>sQ>)orMp>&^dzEo15mFV#=ofd`|
z<31i>Kh<JhP)ihzbzD7K=twe_8dhhl;BS*Z$1$cj;nOJj@$IAYBgu$${3sSWO81HV
zsLx9D__t;o6O8y|<g;;%)6|ofPn@14Bi8f%EYefTT6$BTmFU4|l3^XEd_GfZqC2>Q
zef~Wy=`znB)n~@~?%sYs|NPY4H}>uK*@@o9MD(sv-wB3^Z>`zZG7{_QJ^V1&6Y66A
zYBb?%Tj6Wbja8mBw%(-CnD_D7r#Wv_A9JtHNccO?gkJ`a=Wak7Fbi0C^ar?}|Kf%Y
zb>Q+GSo72y(*N(&|Neh@0+m@EPzV0F1E$&E?e|C%dg}_I^xBs59;Xb+D?GXqF0LIX
hx^|qn_=h2{EmNf?3s`vM4u^gba5m_o4*XRIegZG(532wG