Clarify status of text format, add example, and remove confusing language (#850)

* clarify status of text format, add example, and remove confusing language

* formatting nit

* replace linear section, add 'should' to design section

1 files changed, 98 insertions, 57 deletions

diff --git a/TextFormat.md b/TextFormat.md
index a1953fe..1f25ca3 100644
--- a/TextFormat.md
+++ b/TextFormat.md
@@ -1,64 +1,76 @@
 # Text Format
 
-The purpose of this text format is to support:
-
-* View Source on a WebAssembly module, thus fitting into the Web (where every
-  source can be viewed) in a natural way.
-* Presentation in browser development tools when source maps aren't present
-  (which is necessarily the case with [the Minimum Viable Product (MVP)](MVP.md)).
-* Writing WebAssembly code directly for reasons including pedagogical,
-  experimental, debugging, optimization, and testing of the spec itself.
-
-The text format is equivalent and isomorphic to the [binary format](BinaryEncoding.md).
-
-The text format will be standardized, but only for tooling purposes:
-
-* Compilers will support this format for `.S` and inline assembly.
-* Debuggers and profilers will present binary code using this textual format.
-* Browsers will not parse the textual format on regular web content in order to
-  implement WebAssembly semantics.
-
-Given that the code representation is actually an
-[Abstract Syntax Tree](Semantics.md), the syntax would contain nested
-statements and expressions (instead of the linear list of instructions most
-assembly languages have).
-
-There is no requirement to use JavaScript syntax; this format is not intended to
-be evaluated or translated directly into JavaScript. There may also be
-substantive reasons to use notation that is different than JavaScript (for
-example, WebAssembly has a 32-bit integer type, and it should be represented
-in the text format, since that is the natural thing to do for WebAssembly,
-regardless of JavaScript not having such a type). On the other hand,
-when there are no substantive reasons and the options are basically
-bikeshedding, then it does make sense for the text format to match existing
-conventions on the Web (for example, curly braces, as in JavaScript and CSS).
-
-The text format isn't uniquely representable. Multiple textual files can assemble
-to the same binary file, for example whitespace isn't relevant and memory initialization
-can be broken out into smaller pieces in the text format.
-
-The text format is precise in that values that cannot be accurately represented in the
-binary format are considered invalid text. Floating-point numbers are therefore
-represented as hexadecimal floating-point as specified by the C99 standard, which
-IEEE-754-2008 section 5.12.3 also specifies. The textual format may be improved to also
-support more human-readable representations, but never at the cost of accurate representation.
-
-# Official Text Format
-
-WebAssembly currently doesn't have a final, official, text format. As detailed above the
-main purpose of the text format will be for human consumption, feedback from humans on
-readability will therefore factor into standardizing a text format.
-
-There are, however, prototype syntaxes which are used to bring up WebAssembly: it's easier
-to develop using a text format than it is with a binary format, even if the ultimate
-WebAssembly format will be binary. Most of these prototypes use [s-expressions][] because they
-can easily represent expression trees and [ASTs](Semantics.md) (as opposed to CFGs)
-and don't have much of a syntax to speak of (avoiding syntax bikeshed discussions).
+WebAssembly does not yet have a standardized text format that encodes function
+bodies in addition to module structure, data segments and other program
+metadata in a way that is eqivalent to the [binary format](BinaryEncoding.md).
+WebAssembly does, however, have a specified
+[textual representation](#linear-bytecode) of function bodies which should be displayed in browsers and other tools when [debugging](#debug-symbol-integration)
+modules.
+
+# Linear bytecode
+
+WebAssembly function bodies encode bytecode instructions which have specified canonical opcode names. A linear presentation of these sequences of instructions allows a direct human-readable order-preserving presentation of the binary format. This format is suitable for opcode by opcode inspection of a WebAssembly program and can readily be related to the [sematics](Semantics.md) of the format. 
+
+Here is an example function illustrated in C++, binary, and text (linear
+assembly bytecode):
+
+<table>
+  <tr>
+    <th>C++</th>
+    <th>Binary</th>
+    <th>Text</th>
+  </tr>
+  <tr>
+    <td><pre>
+int factorial(int n) {
+  if (n == 0)
+    return 1;
+  else
+    return n * fac(n-1);
+}</pre></td>
+    <td><pre>
+20 00
+42 00
+51
+04 7e
+42 01
+05
+20 00
+20 00
+42 01
+7d
+10 00
+7e
+0b</pre></td>
+    <td><pre>
+get_local 0
+i64.const 0
+i64.eq
+if i64
+    i64.const 1
+else
+    get_local 0
+    get_local 0
+    i64.const 1
+    i64.sub
+    call 0
+    i64.mul
+end</pre></td>
+  </tr>
+</table>
+
+# Tool conventions
+
+Most WebAssembly tools currently use [s-expressions][] to represent modules in a
+textual format. Although the s-expression format is not an official text format,
+it is a tooling convention because it allows for the representation of function
+signatures, declarations, and other metadata and it doesn't have much of a
+syntax to speak of (avoiding syntax bikeshed discussions).
 
   [s-expressions]: https://en.wikipedia.org/wiki/S-expression
 
-Here are some of these prototypes. Keep in mind that these *aren't* official, and the final
-official format may look entirely different:
+Here are some of these prototypes. Keep in mind that these *aren't* official,
+and the final standard format may look entirely different:
 
 * [Prototype specification][] consumes an s-expression syntax.
 * [WAVM backend][] consumes compatible s-expressions.
@@ -75,7 +87,7 @@ official format may look entirely different:
   [wabt]: https://github.com/WebAssembly/wabt
   [binaryen]: https://github.com/WebAssembly/binaryen
 
-# Debug symbol integration
+## Debug symbol integration
 
 The binary format inherently strips names from functions, locals, globals, etc,
 reducing each of these to dense indices. Without help, the text format must
@@ -83,3 +95,32 @@ therefore synthesize new names. However, as part of the [tooling](Tooling.md)
 story, a lightweight, optional "debug symbol" global section may be defined
 which associates names with each indexed entity and, when present, these names
 will be used in the text format projected from a binary WebAssembly module.
+
+# Future design :unicorn:
+
+An official text format capable of representing WebAssembly modules needs a
+way of encoding, in addition to function bodies: declarations, function
+signatures, data segments, tables, and other
+[sections](BinaryEncoding.md#high-level-structure) of the binary format.
+
+In addition, expansions or extensions to a standardized text format may offer
+additional syntactic sugar, macro expansions, or other conveniences to make it
+easier to write and read WebAssembly. However, since the linear sequence of
+bytecodes in a binary module may have more than one higher-level
+representation, such sugar or conveniences may not be possible to resolve
+canonically from the binary format alone.
+
+The design goals for a WebAssembly text format derive from the following use
+cases:
+
+* View Source on a WebAssembly module, thus fitting into the Web (where every source can be viewed) in a natural way.
+* Presentation in browser development tools when source maps aren't present (which is necessarily the case with [the Minimum Viable Product (MVP)](MVP.md)).
+* Writing WebAssembly code directly for reasons including pedagogical, experimental, debugging, optimization, and testing of the spec itself.
+
+## Additional design considerations
+
+There is no requirement to use JavaScript syntax; this format is not intended to be evaluated or translated directly into JavaScript. There may also be substantive reasons to use notation that is different than JavaScript (for example, WebAssembly has a 64-bit integer type, and it should be represented in the text format, since that is the natural thing to do for WebAssembly, regardless of JavaScript not having such a type). On the other hand, when there are no substantive reasons and the options are basically bikeshedding, then it does make sense for the text format to match existing conventions on the Web (for example, curly braces, as in JavaScript and CSS).
+
+The text format may not be uniquely representable. Multiple textual files will likley assemble to the same binary file. For example, whitespace shouldn't be significant and memory initialization can be broken out into smaller pieces in a text format.
+
+The text format should be precise in that values that cannot be accurately represented in the binary format are considered invalid text. Floating-point numbers should therefore be represented as hexadecimal floating-point as specified by C99, C++17, and IEEE-754-2008 section 5.12.3. The textual format may be improved to also support more human-readable representations, but never at the cost of accurate representation.
\ No newline at end of file