From 221821f00af18e60938042fb52bc7c5ad50723ff Mon Sep 17 00:00:00 2001
From: Dan Gohman <sunfish@mozilla.com>
Date: Thu, 5 Sep 2019 12:25:59 -0700
Subject: [PATCH] Add a document on `witx`.

---
 design/wasi_unstable/typenames.witx     |  3 +++
 design/wasi_unstable/wasi_unstable.witx |  3 +++
 docs/witx.md                            | 30 +++++++++++++++++++++++++
 3 files changed, 36 insertions(+)
 create mode 100644 docs/witx.md

diff --git a/design/wasi_unstable/typenames.witx b/design/wasi_unstable/typenames.witx
index 021c750a..14fd81e4 100644
--- a/design/wasi_unstable/typenames.witx
+++ b/design/wasi_unstable/typenames.witx
@@ -1,6 +1,9 @@
 ;; Type names used by the wasi_unstable module type.
 ;;
 ;; Some content here is derived from [CloudABI](https://github.com/NuxiNL/cloudabi).
+;;
+;; This is a `witx` file. See [here](https://github.com/WebAssembly/WASI/tree/master/docs/witx.md)
+;; for an explanation of what that means.
 
 (typename $size_t u32)
 
diff --git a/design/wasi_unstable/wasi_unstable.witx b/design/wasi_unstable/wasi_unstable.witx
index 82b75ef2..c47541b9 100644
--- a/design/wasi_unstable/wasi_unstable.witx
+++ b/design/wasi_unstable/wasi_unstable.witx
@@ -1,6 +1,9 @@
 ;; The wasi_unstable module type.
 ;;
 ;; Some content here is derived from [CloudABI](https://github.com/NuxiNL/cloudabi).
+;;
+;; This is a `witx` file. See [here](https://github.com/WebAssembly/WASI/tree/master/docs/witx.md)
+;; for an explanation of what that means.
 
 (use "typenames.wid")
 
diff --git a/docs/witx.md b/docs/witx.md
new file mode 100644
index 00000000..db267992
--- /dev/null
+++ b/docs/witx.md
@@ -0,0 +1,30 @@
+# Know your `witx`
+
+The `witx` file format is an experimental format which is based on the
+[module types] text format (`wit`), (which is in turn based on the
+[wat format], which is based on [S-expressions]). It adds some features
+using the same syntax as [interface types], some features with syntax
+similar to [gc types], as well as a few special features of its own.
+
+`witx` is actively evolving. Expect backwards-incompatible changes,
+particularly in the areas where `witx` differs from `wit`.
+
+The initial goal for `witx` is just to have a language suitable for
+expressing [WASI] APIs in, to serve as the vocabulary for proposing changes
+to existing APIs and proposing new APIs. Initially, while it uses some of
+the syntax and concepts from interface types, it doesn't currently imply the
+full interface types specification, or the use of the interface types custom
+sections.
+
+We expect that eventually we will transition to using the full interface
+types specification. Until then, the goals here are to remain aligned with
+interface types and other relevant WebAssembly standards and proposals
+wherever practical, and to be an input into the design process of interface
+types.
+
+[module types]: https://github.com/WebAssembly/module-types/blob/master/proposals/module-types/Overview.md
+[interface types]: https://github.com/WebAssembly/interface-types/blob/master/proposals/interface-types/Explainer.md
+[gc types]: https://github.com/WebAssembly/gc
+[wat format]: https://webassembly.github.io/spec/core/bikeshed/index.html#text-format%E2%91%A0
+[S-expressions]: https://en.wikipedia.org/wiki/S-expression
+[WASI]: https://github.com/WebAssembly/WASI