Fixup links to future features (#1157)

josephlr · jfbastien · commit e2be77eaac77 · 2017-11-15T09:48:14.000-07:00
This link standardizes how all the other design pages will refer to
future features (either in `FutureFeatures.md` or in a tracking issue).
All links to these upcoming features now use references at the bottom of
the doc page (as opposed to inline links or references).

Note that this change makes it very easy for the doc links to be updated
when a tracking issue is started. As all the references have a standard
format; a simple find/replace script will get everything.

This commit also makes sure that references now point to a tracking
issue if one exists. Note that this means a future CL can now delete
some of the unnecessary sections from `FutureFeatures.md`.

The only visible change from this commit is that certain broken links
are now fixed, or links pointing to a doc section now point to the
correct tracking issue.
diff --git a/BinaryEncoding.md b/BinaryEncoding.md
@@ -57,7 +57,7 @@ Note: Currently, the only sizes used are `varint7`, `varint32` and `varint64`.
 
 In the MVP, the opcodes of [instructions](Semantics.md) are all encoded in a
 single byte since there are fewer than 256 opcodes. Future features like
-[SIMD](FutureFeatures.md#fixed-width-simd) and [atomics](FutureFeatures.md#threads)
+[SIMD][future simd] and [atomics][future threads]
 will bring the total count above 256 and so an extension scheme will be
 necessary, designating one or more single-byte values as prefixes for multi-byte
 opcodes.
@@ -811,8 +811,9 @@ for [future :unicorn:][future multiple tables] use and must be 0 in the MVP.
 | `f64.reinterpret/i64` | `0xbf` | | |
 
 [future general]: FutureFeatures.md
-[future multiple return]: FutureFeatures.md#multiple-return
-[future threads]: FutureFeatures.md#threads
+[future multiple return]: https://github.com/WebAssembly/design/issues/1146
+[future threads]: https://github.com/WebAssembly/design/issues/1073
+[future simd]: https://github.com/WebAssembly/design/issues/1075
 [future types]: FutureFeatures.md#more-table-operators-and-types
 [future multiple tables]: FutureFeatures.md#multiple-tables-and-memories
 [future compression]: https://github.com/WebAssembly/decompressor-prototype/blob/master/CompressionLayer1.md
diff --git a/CAndC++.md b/CAndC++.md
@@ -41,13 +41,13 @@ compilers need to support high-quality implementations.
 While [the MVP](MVP.md) will be fully functional, additional features enabling
 greater performance will be added soon after, including:
 
- * [Support for multi-threaded execution with shared memory](FutureFeatures.md#threads).
+ * Support for [multi-threaded execution with shared memory][future threads].
 
- * [Zero-cost C++ exception handling](FutureFeatures.md#zero-cost-exception-handling).
+ * [Zero-cost C++ exception handling][future exceptions].
    C++ exceptions can be implemented without this, but this feature will
    enable them to have lower runtime overhead.
 
- * Support for [128-bit SIMD](FutureFeatures.md#fixed-width-simd). SIMD will be
+ * Support for [128-bit SIMD][future simd]. SIMD will be
    exposed to C/C++ though explicit APIs such as [LLVM's vector extensions]
    and [GCC's vector extensions], auto-vectorization, and emulated APIs from
    other platforms such as `<xmmintrin.h>`.
@@ -128,4 +128,7 @@ across different implementations, and across different versions of the same
 implementation.
 
 [future 64-bit]: FutureFeatures.md#linear-memory-bigger-than-4-gib
+[future threads]: https://github.com/WebAssembly/design/issues/1073
+[future simd]: https://github.com/WebAssembly/design/issues/1075
+[future exceptions]: https://github.com/WebAssembly/design/issues/1078
 
diff --git a/FAQ.md b/FAQ.md
@@ -24,7 +24,7 @@ There are two main benefits WebAssembly provides:
 2. By avoiding the simultaneous asm.js constraints of [AOT][]-[compilability][]
    and good performance even on engines without
    [specific asm.js optimizations][], a new standard makes it *much easier* to
-   add the [features :unicorn:][future features] required to reach native
+   add the [features :unicorn:][future general] required to reach native
    levels of performance.
 
   [experiments]: BinaryEncoding.md#why-a-binary-encoding-instead-of-a-text-only-representation
@@ -96,7 +96,7 @@ reusing a modular C++ library can be as simple as [using a module from JavaScrip
 Beyond the MVP, another [high-level goal](HighLevelGoals.md)
 is to improve support for languages other than C/C++.  This includes [allowing WebAssembly code to
 allocate and access garbage-collected (JavaScript, DOM, Web API) objects
-:unicorn:][future dom].
+:unicorn:][future garbage collection].
 Even before GC support is added to WebAssembly, it is possible to compile a language's VM 
 to WebAssembly (assuming it's written in portable C/C++) and this has already been demonstrated 
 ([1](http://ruby.dj), [2](https://kripken.github.io/lua.vm.js/lua.vm.js.html),
@@ -178,7 +178,7 @@ together in a number of configurations:
   today) allowing developers to reuse popular WebAssembly libraries just like
   JavaScript libraries today.
 * When WebAssembly
-  [gains the ability to access garbage-collected objects :unicorn:][future dom],
+  [gains the ability to access garbage-collected objects :unicorn:][future garbage collection],
   those objects will be shared with JavaScript, and not live in a walled-off
   world of their own.
 
@@ -390,7 +390,7 @@ accessible through regular JavaScript. However, if a wasm VM is provided as an
 access to [proprietary platform-specific APIs](Portability.md#api) of e.g. 
 Android / iOS. 
 
-[future features]: FutureFeatures.md
-[future dom]: FutureFeatures.md#gcdom-integration
+[future general]: FutureFeatures.md
+[future garbage collection]: https://github.com/WebAssembly/design/issues/1079
 [future floating point]: FutureFeatures.md#additional-floating-point-operators
 [future memory control]: FutureFeatures.md#finer-grained-control-over-memory
diff --git a/FeatureTest.md b/FeatureTest.md
@@ -103,6 +103,6 @@ future feature.
 [future general]: FutureFeatures.md
 [future feature testing]: FutureFeatures.md#feature-testing
 [future integer]: FutureFeatures.md#additional-integer-operators
-[future threads]: FutureFeatures.md#threads
-[future simd]: FutureFeatures.md#fixed-width-simd
+[future threads]: https://github.com/WebAssembly/design/issues/1073
+[future simd]: https://github.com/WebAssembly/design/issues/1075
 [future memory control]: FutureFeatures.md#finer-grained-control-over-memory
diff --git a/FutureFeatures.md b/FutureFeatures.md
@@ -421,15 +421,13 @@ arithmetic, or optimizing JavaScript Numbers to use int32 operators. Another fam
 includes compiling code that doesn't expect overflow to occur, but which wishes
 to have overflow detected and reported if it does happen. These use cases would
 ideally like to have overflow trap, and to allow them to
-[handle trap specially][]. Following the rule that explicitly signed and
+[handle trap specially][future trapping]. Following the rule that explicitly signed and
 unsigned operators trap whenever the result value can not be represented in the
 result type, it would be possible to add explicitly signed and unsigned versions
 of integer `add`, `sub`, and `mul`, which would trap on overflow. The main
 reason we haven't added these already is that they're not efficient for
 general-purpose use on several of today's popular hardware architectures.
 
-  [handle trap specially]: FutureFeatures.md#trapping-or-non-trapping-strategies
-
 ### Better feature testing support
 
 The [MVP feature testing situation](FeatureTest.md) could be improved by
@@ -455,7 +453,7 @@ of supporting multiple return values from blocks / functions.
 The MVP limits modules to at most one memory and at most one table (the default
 ones) and there are only operators for accessing the default table and memory.
 
-After the MVP and after [GC reference types](https://github.com/WebAssembly/design/issues/1079) have been added, the default
+After the MVP and after [GC reference types][future garbage collection] have been added, the default
 limitation can be relaxed so that any number of tables and memories could be
 imported or internally defined and memories/tables could be passed around as
 parameters, return values and locals. New variants of `load`, `store`
@@ -476,7 +474,7 @@ see [JavaScript's `WebAssembly.Table` API](JS.md#webassemblytable-objects)).
 It would be useful to be able to do everything from within WebAssembly so, e.g.,
 it was possible to write a WebAssembly dynamic loader in WebAssembly. As a
 prerequisite, WebAssembly would need first-class support for 
-[GC references](https://github.com/WebAssembly/design/issues/1079) on the stack and in locals. Given that, the following
+[GC references][future garbage collection] on the stack and in locals. Given that, the following
 could be added:
 
 * `get_table`/`set_table`: get or set the table element at a given dynamic
@@ -514,3 +512,6 @@ We expect that WebAssembly producers will use these operations when the region
 size is known to be large, and will use loads/stores otherwise.
 
 TODO: determine how these operations interact w/ shared memory.
+
+[future trapping]: FutureFeatures.md#trapping-or-non-trapping-strategies
+[future garbage collection]: https://github.com/WebAssembly/design/issues/1079
diff --git a/HighLevelGoals.md b/HighLevelGoals.md
@@ -10,10 +10,10 @@
     * a [Minimum Viable Product (MVP)](MVP.md) for the standard with
       roughly the same functionality as [asm.js](http://asmjs.org), primarily
       aimed at [C/C++](CAndC++.md);
-    * [additional features :unicorn:][future features],
-      initially focused on key features like threads,
-      zero cost exceptions, and SIMD,
-      follow by additional features
+    * [additional features :unicorn:][future general],
+      initially focused on key features like [threads][future threads],
+      [zero cost exceptions][future exceptions], and [SIMD][future simd],
+      followed by additional features
       prioritized by feedback and experience, including support for languages
       other than C/C++.
 3. Design to execute within and integrate well with the *existing*
@@ -33,4 +33,7 @@
     * promote other compilers and tools targeting WebAssembly; and
     * enable other useful [tooling](Tooling.md).
 
-[future features]: FutureFeatures.md
+[future general]: FutureFeatures.md
+[future threads]: https://github.com/WebAssembly/design/issues/1073
+[future simd]: https://github.com/WebAssembly/design/issues/1075
+[future exceptions]: https://github.com/WebAssembly/design/issues/1078
diff --git a/JITLibrary.md b/JITLibrary.md
@@ -1,7 +1,6 @@
 # JIT and Optimization Library
 
-WebAssembly's
-[Just-in-Time compilation (JIT)](FutureFeatures.md#platform-independent-just-in-time-jit-compilation)
+WebAssembly's [Just-in-Time compilation (JIT)][future jit control]
 interface will likely be fairly low-level, exposing general-purpose primitives
 rather than higher-level functionality. Still, there is a need for higher-level
 functionality, and for greater flexibility than the WebAssembly spec can provide.
@@ -85,3 +84,5 @@ A significant range of approaches are possible:
     would allow a unique degree of flexibility.
 
   * And many things in between.
+
+[future jit control]: FutureFeatures.md#platform-independent-just-in-time-jit-compilation
diff --git a/Modules.md b/Modules.md
@@ -6,7 +6,7 @@ with a set of import values to produce an **instance**, which is an immutable
 tuple referencing all the state accessible to the running module. Multiple
 module instances can access the same shared state which is the basis for 
 [dynamic linking](DynamicLinking.md) in WebAssembly. WebAssembly modules
-are also meant to integrate with ES6 modules in the [future :unicorn:][future ES6 modules].
+are also meant to integrate with ES6 modules in the [future :unicorn:][future modules].
 
 A module contains the following sections:
 
@@ -327,8 +327,7 @@ to the following nullary operators:
 In the future, operators like `i32.add` could be added to allow more expressive
 `base + offset` load-time calculations.
 
-[future ES6 modules]: FutureFeatures.md#tracking-issues
+[future modules]: https://github.com/WebAssembly/design/issues/1087
 [future types]: FutureFeatures.md#more-table-operators-and-types
-[future dom]: FutureFeatures.md#gc/dom-integration
 [future multiple tables]: FutureFeatures.md#multiple-tables-and-memories
 [valid UTF-8]: https://encoding.spec.whatwg.org/#utf-8-decode-without-bom-or-fail
diff --git a/Nondeterminism.md b/Nondeterminism.md
@@ -52,5 +52,5 @@ have defined or constrained behavior in WebAssembly itself may nonetheless still
 have undefined behavior
 [at the source code level](CAndC++.md#undefined-behavior).
 
-[future threads]: FutureFeatures.md#threads
-[future simd]: FutureFeatures.md#fixed-width-simd
+[future threads]: https://github.com/WebAssembly/design/issues/1073
+[future simd]: https://github.com/WebAssembly/design/issues/1075
diff --git a/Portability.md b/Portability.md
@@ -32,7 +32,7 @@ characteristics:
 * Memory regions which can be efficiently addressed with 32-bit
   pointers or indices.
 * wasm64 additionally supports linear memory bigger than
-  [4 GiB with 64-bit pointers or indices](FutureFeatures.md#linear-memory-bigger-than-4-gib).
+  [4 GiB with 64-bit pointers or indices][future 64-bit].
 * Enforce secure isolation between WebAssembly modules and other modules or
   processes executing on the same machine.
 * An execution environment which offers forward progress guarantees to all
@@ -60,3 +60,5 @@ a standard API (e.g., POSIX) and relying on the compiler and/or libraries to map
 the standard interface to the host environment's available imports either at
 compile-time (via `#ifdef`) or run-time (via [feature detection](FeatureTest.md)
 and dynamic [loading](Modules.md)/[linking](DynamicLinking.md)).
+
+[future 64-bit]: FutureFeatures.md#linear-memory-bigger-than-4-gib
diff --git a/README.md b/README.md
@@ -33,7 +33,7 @@ The WebAssembly specification is being developed in the [spec repository](https:
 We've mapped out features we expect to ship:
 
  1. An initial [Minimum Viable Product (MVP)](MVP.md) release;
- 2. And soon after in [future versions](FutureFeatures.md).
+ 2. And soon after in [future versions][future general].
 
 Join us:
 
@@ -47,3 +47,5 @@ Join us:
  * By [contributing](Contributing.md)!
 
 When contributing, please follow our [Code of Ethics and Professional Conduct](CodeOfConduct.md).
+
+[future general]: FutureFeatures.md
diff --git a/Rationale.md b/Rationale.md
@@ -153,8 +153,8 @@ address a number of competing constraints:
    implementation details.)
 3. Avoid *forcing* every developer using WebAssembly to understand their precise
    maximum heap usage.
-4. When threading and shared memory are added to WebAssembly
-   [post-MVP](FutureFeatures.md#threads), the design should not require memory growth
+4. When [threading and shared memory][future threads] are added to WebAssembly
+   post-MVP, the design should not require memory growth
    to `realloc` since this implies significant implementation complexity,
    security hazards, and optimization challenges.
 
@@ -457,7 +457,7 @@ hardware platforms.
 ## Motivating Scenarios for Feature Testing
 
 1. [Post-MVP :unicorn:][future general],
-[`i32.min_s` :unicorn:][future integers] is introduced. A
+[`i32.min_s` :unicorn:][future integer] is introduced. A
 WebAssembly developer updates their toolkit so that the compiler may leverage
 `i32.min_s`. The developer's WebAssembly module works correctly both on
 execution environments at MVP, as well as those supporting `i32.min_s`.
@@ -470,7 +470,7 @@ possible. The developer has to balance the cost of the test matrix resulting
 from the combinations of possible feature configurations.
 
 2. [Post-MVP :unicorn:][future general], module authors may now use
-[Threading](FutureFeatures.md#threads)
+[Threading][future threads]
 APIs in the browser. A developer wants to leverage multithreading in their
 module.
 
@@ -483,7 +483,7 @@ need MVP support.
   * In another variant, our developer explicitly authors both MVP-only and post-
 MVP (with threads) code.
 
-3. [SIMD](FutureFeatures.md#fixed-width-simd) support is not universally
+3. [SIMD][future simd] support is not universally
 equivalent on all targets. While polyfill variants of SIMD APIs are available,
 a developer prefers writing dedicated SIMD and non-SIMD versions of their
 compression algorithm, because the non-SIMD version performs better in
@@ -563,10 +563,6 @@ Yes:
 * [Existing web standards](https://www.w3.org/TR/PNG/) demonstrate many of
   the advantages of a layered encoding strategy.
 
-[future general]: FutureFeatures.md
-[future flow control]: FutureFeatures.md#more-expressive-control-flow
-[future integers]: FutureFeatures.md#additional-integer-operations
-
 
 ## Why "polymorphic" stack typing after control transfer?
 
@@ -607,3 +603,9 @@ It is worth noting that this kind of type checking, in general, is not unusual.
 For example, the JVM also poses no constraint on the stack type after a jump (however, in its modern form, it recommends type annotations in the form of _stack maps_, which are then required after jumps to make the instantiation of the polymorphic typing rule explicit).
 Moreover, programming languages that allow control transfer _expressions_ usually type them polymorphically as well (e.g., `throw`/`raise`, which is an expression in some languages).
 
+
+[future general]: FutureFeatures.md
+[future flow control]: FutureFeatures.md#more-expressive-control-flow
+[future integer]: FutureFeatures.md#additional-integer-operations
+[future threads]: https://github.com/WebAssembly/design/issues/1073
+[future simd]: https://github.com/WebAssembly/design/issues/1075
diff --git a/Security.md b/Security.md
@@ -58,13 +58,13 @@ compile time. This is an isolated memory region with fixed maximum size that is
 zero initialized by default. References to this memory are computed with
 infinite precision to avoid wrapping and simplify bounds checking. In the future,
 support for [multiple linear memory sections](Modules.md#linear-memory-section) and
-[finer-grained memory operations](FutureFeatures.md#finer-grained-control-over-memory)
+[finer-grained memory operations][future memory control]
 (e.g. shared memory, page protection, large pages, etc.) will be implemented.
 
 [Traps](Semantics.md#traps) are used to immediately terminate execution and
 signal abnormal behavior to the execution environment. In a browser, this is
 represented as a JavaScript exception. Support for
-[module-defined trap handlers](FutureFeatures.md#trappingor-non-trapping-strategies)
+[module-defined trap handlers][future trapping]
 will be implemented in the future. Operations that can trap include:
 
   * specifying an invalid index in any index space,
@@ -180,4 +180,6 @@ in WebAssembly.
   [stack smashing protection]: https://en.wikipedia.org/wiki/Buffer_overflow_protection#Random_canaries
   [time of check to time of use]: https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use
 
-[future threads]: FutureFeatures.md#threads
+[future threads]: https://github.com/WebAssembly/design/issues/1073
+[future memory control]: FutureFeatures.md#finer-grained-control-over-memory
+[future trapping]: FutureFeatures.md#trapping-or-non-trapping-strategies
diff --git a/Semantics.md b/Semantics.md
diff --git a/Web.md b/Web.md
