Add a README

1 files changed, 85 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..ab4a50f
--- /dev/null
+++ b/README
@@ -0,0 +1,85 @@
+                       ──────────────────────────────────
+                         Pinocchio — Truth Table Solver
+                       ──────────────────────────────────
+
+NOTE:  For interactive usage, consider running Pinocchio within an
+       instance of rlwrap[1].
+
+Pinocchio is a simple truth-table solver supporting both ASCII/UTF-8 and
+LaTeX output — perfect for repetitive university assignments.
+
+When run without arguments, Pinocchio reads queries from the standard
+input and prints truth tables to the standard output.  If given
+one-or-more non-option command-line arguments, the arguments are treated
+as newline-separated lists of queries.  The special filename ‘-’ may be
+used to denote the standard input.  The -s/--string option may also be
+used to provide a query directly to Pinocchio as a command-line argument.
+
+Here is a quick example of Pinocchio usage.  Individual expressions to be
+shown in the generated table are separated by a vertical-bar (‘|’).
+
+	$ pinocchio -s 'a ∧ b | a ∨ b'
+	a b │ a ∧ b │ a ∨ b
+	────┼───────┼──────
+	0 0 │   0   │   0
+	0 1 │   0   │   1
+	1 0 │   0   │   1
+	1 1 │   1   │   1
+	$ LC_ALL=C pinocchio -s 'a ∧ b | a ∨ b'
+	a b | a && b | a || b
+	----+--------+-------
+	0 0 |    0   |   0
+	0 1 |    0   |   1
+	1 0 |    0   |   1
+	1 1 |    1   |   1
+	$
+
+Each vertical-bar-separated expression in the query may refer to
+zero-or-more variables, where a variable is any lower- or uppercase ASCII
+character (Unicode or multi-character variables are not supported).
+Operators may also be written using either the corresponding Unicode
+character or by using an ASCII alternative with C-like (but not
+identical) syntax.
+
+The list of operators are as follows:
+
+	Name         │ Operator
+	─────────────┼─────────
+	Negation     │ ¬, !
+	Conjunction  │ ∧, &&
+	Disjunction  │ ∨, ||
+	Exclusive Or │ ⊻, ⊕, ~
+	Implication  │ ⇒, =>
+	Equivalence  │ ⇔, <=>
+
+By default generated tables express boolean values as the binary digits 0
+and 1, and are drawn using ASCII characters or Unicode characters if the
+user is in a UTF-8 locale.  This can all be customized with use of the
+-t/--table-style and -b/--bool-style flags.
+
+The -t/--table-style flag accepts one of the following styles as a
+parameter:
+
+	Name  │ Description
+	──────┼──────────────────────────────────────────────────────────────
+	ascii │ Draw the table using ASCII characters and C-like ASCII
+	      │ operators.
+	      │
+	utf8  │ Draw the table using Unicode box-drawing characters and
+	      │ Unicode mathematical operators.
+	      │
+	latex │ Output LaTeX markup suitable for embedding within a document.
+	      │ Note that you may need to include the \usepackage{amsmath}
+	      │ directive for certain symbols to render.
+
+The -b/--bool-style flag accepts one of the following styles as a
+parameter:
+
+	Name    │ Symbols
+	────────┼─────────
+	alpha   │ T, F
+	binary  │ 0, 1
+	symbols │ ⊤, ⊥
+
+
+[1]: https://github.com/hanslub42/rlwrap