Minor docs improvements (#1774)

* Fix some botched formatting (replace ```mdoc scala with ```scala mdoc)
* Replace some unnecessary uses of triple backticks with single
  backticks
* Move appendix docs from wiki-deprecated/ to appendix/
  * This will require an update on the website as well
* Update Bundle literal docs

3 files changed, 429 insertions, 0 deletions

diff --git a/docs/src/appendix/chisel3-vs-chisel2.md b/docs/src/appendix/chisel3-vs-chisel2.md
new file mode 100644
index 00000000..bfd20348
--- /dev/null
+++ b/docs/src/appendix/chisel3-vs-chisel2.md
@@ -0,0 +1,203 @@
+---
+layout: docs
+title:  "Chisel3 vs. Chisel2"
+section: "chisel3"
+---
+
+# Chisel3 vs Chisel2
+
+## Chisel2 Migration
+For those moving from Chisel2, there were some backwards incompatible changes
+and your RTL needs to be modified to work with Chisel3. The required
+modifications are:
+
+ - Wire declaration style:
+   ```scala
+   val wire = UInt(width = 15)
+   ```
+   becomes (in Chisel3):
+   ```scala
+   val wire = Wire(UInt(15.W))
+   ```
+
+ - I/O declaration style:
+   ```scala
+   val done = Bool(OUTPUT)
+   ```
+   becomes (in Chisel3):
+   ```scala
+   val wire = Output(Bool())
+   ```
+
+ - Sequential memories:
+   ```scala
+   val addr = Reg(UInt())
+   val mem = Mem(UInt(8.W), 1024, seqRead = true)
+   val dout = when(enable) { mem(addr) }
+   ```
+   becomes (in Chisel3):
+   ```scala
+   val addr = UInt()
+   val mem = SyncReadMem(1024, UInt(8.W))
+   val dout = mem.read(addr, enable)
+   ```
+
+   Notice the address register is now internal to the SyncReadMem(), but the data
+   will still return on the subsequent cycle.
+
+ - Generating Verilog with
+   ```scala
+   object Hello {
+     def main(args: Array[String]): Unit = {
+       chiselMain(Array("--backend", "v"), () => Module(new Hello()))
+     }
+   }
+   ```
+   becomes (in Chisel3):
+   ```scala
+   object Hello {
+     def main(args: Array[String]): Unit = {
+       chisel3.Driver.execute(Array[String](), () => new Hello())
+     }
+   }
+   ```
+
+ - Package changes:
+   - Chisel.log2Ceil -> chisel3.util.log2Ceil
+   - BitPat
+   - Decoupled is also in chisel3.util
+
+Please refer to the [Chisel3 compatibility section](https://github.com/ucb-bar/chisel#chisel3)
+for instructions on preparing your Chisel2 designs for Chisel3.
+
+## Deprecated Usage
+*  `Vec(Reg)` should be replaced with `Reg(Vec)`,
+*  type-only vals (no associated data) must be wrapped in a `Wire()` if they will be the destination of a wiring operation (":=" or " < >"),
+*  masked bit patterns ('b??') should be created using BitPat(), not UInt() or Bits(),
+*  the `clone` method required for parameterized Bundles has been renamed `cloneType`,
+*  the con and alt inputs to a Mux must be type-compatible - both signed or both unsigned,
+*  bulk-connection to a node that has been procedurally assigned-to is illegal,
+*  `!=` is deprecated, use `=/=` instead,
+*  use `SyncReadMem(...)` instead of `Mem(..., seqRead)`,
+*  use `SyncReadMem(n:Int, out: => T)` instead of `SyncReadMem(out: => T, n:Int)`,
+*  use `SyncReadMem(...)` instead of `SeqMem(...)`,
+*  use `Mem(n:Int, t:T)` instead of `Mem(out:T, n:Int)`,
+*  use `Vec(n:Int, gen: => T)` instead of `Vec(gen: => T, n:Int)`,
+*  module io's must be wrapped in `IO()`.
+*  The methods `asInput`, `asOutput`, and `flip` should be replaced by the `Input()`, `Output()`, and `Flipped()` object apply methods.
+
+## Unsupported constructs
+*  `Mem(..., orderedWrites)` is no longer supported,
+*  masked writes are only supported for `Mem[Vec[_]]`,
+* Chisel3 Vecs must all have the same type, unlike with Chisel2. Use `MixedVec` (see [Bundles and Vecs](../explanations/bundles-and-vecs)) for Vecs where the elements are of different types.
+*  connections between `UInt` and `SInt` are illegal.
+*  the `Node` class and object no longer exist (the class should have been private in Chisel2)
+*  `printf()` is defined in the Chisel object and produces simulation printf()'s.
+To use the Scala `Predef.printf()`, you need to qualify it with `Predef`.
+*  in Chisel2, bulk-connects `<>` with unconnected source components do not update connections from the unconnected components.
+** In Chisel3, bulk-connects strictly adhere to last connection semantics and unconnected OUTPUTs will be connected to INPUTs resulting in the assignment of random values to those inputs.
+* In Chisel3, adding hardware inside `BlackBox` for simulation is no longer supported. (#289)
+* `ChiselError` is gone
+  * Change `ChiselError.error("error msg")` to `throw new Error("error msg")`
+  * Change `ChiselError.info("info msg")` to `println("info msg")`
+* In Chisel3, subword assignments are not supported. [Alternative constructions exist](https://github.com/freechipsproject/chisel3/wiki/Cookbook#how-do-i-do-subword-assignment-assign-to-some-bits-in-a-uint) in Chisel3.
+
+## Further changes
+* The clock signal was renamed from `clk` to `clock` in Chisel3.
+* Change `getWidth()` to `getWidth`
+
+## Packaging
+Chisel3 is implemented as several packages.
+The core DSL is differentiated from utility or library classes and objects, testers, and interpreters.
+The prime components of the Chisel3 front end (the DSL and library objects) are:
+* coreMacros - source locators provide Chisel line numbers for `firrtl` detected errors,
+* chiselFrontend - main DSL components,
+* chisel3 - compiler driver, interface packages, compatibility layer.
+
+Due to the wonders of `sbt`, you need only declare a dependency on the chisel3 package, and the others will be downloaded as required.
+
+The `firrtl` compiler is distributed as a separate package, and release versions will also be downloaded automatically as required.
+If you choose to integrate the compiler into your own toolchain, or you're working with the development (master) branch of chisel3, you should clone the [firrtl](https://github.com/ucb-bar/firrtl) repo
+and follow the instructions for installing the `firrtl` compiler.
+
+The testers in Chisel3 are distributed as a separate package.
+If you intend to use them in your tests, you will either need to clone the [chisel-testers](https://github.com/ucb-bar/chisel-testers) repo
+or declare a dependency on the published version of the package.
+See the `build.sbt` file in either the [chisel-template](https://github.com/ucb-bar/chisel-template) or [chisel-tutorial](https://github.com/ucb-bar/chisel-tutorial)
+repos for examples of the latter.
+
+## Simulation
+Chisel2 was capable of directly generating a `C++` simulation from the Chisel code, or a harness for use with a `vcs` simulation.
+Chisel3 relies on [verilator](http://www.veripool.org/wiki/verilator) to generate the `C++` simulation from the Verilog output of `firrtl`.
+See the [Chisel3 README](https://github.com/ucb-bar/chisel3) for directions on installing `verilator`.
+
+## Compile Options and Front End Checks (Strict vs. NotStrict)
+Chisel3 introduces a formal specification for hardware circuit graphs: FIRRTL,
+and Chisel3 itself (the Scala library implementing the Chisel DSL), is a relatively thin front end that generates FIRRTL.
+Since the `firrtl` parser needs to validate FIRRTL input, most of the checks that were performed in Chisel2 were eliminated
+from the initial Chisel3 front end (the DRY principle).
+
+However, this does impact the ability to provide detailed messages for error conditions that could be detected in the Chisel3
+front end. The decision was made to optionally enable stricter error checking (for connections and the use of raw types versus
+hardware objects), based on specific imports.
+This allows designs to move from less strict front end checks (largely compatible with Chisel2), to stricter checking,
+on a file by file basis, by adjusting specific import statements.
+
+```scala
+    import chisel3.core.ExplicitCompileOptions.Strict
+```
+
+enables stricter connection and usage checks, while
+
+```scala
+    import chisel3.core.ExplicitCompileOptions.NotStrict
+```
+
+defers these checks to the `firrtl` compiler.
+
+By default, the `Chisel` compatibility layer, invoked by:
+
+```scala
+    import Chisel._
+```
+
+implicitly defines the compile options as `chisel3.core.ExplicitCompileOptions.NotStrict`
+
+whereas the Chisel3 package, invoked by:
+
+```scala
+    import chisel3._
+```
+
+implicitly defines the compile options as `chisel3.core.ExplicitCompileOptions.Strict`
+
+Again, these implicit compile options definitions may be overridden by explicit imports.
+
+Currently, the specific error checks (found in [CompileOptions.scala](https://github.com/ucb-bar/chisel3/blob/master/chiselFrontend/src/main/scala/chisel3/core/CompileOptions.scala)) are:
+
+```scala
+    trait CompileOptions {
+      // Should Bundle connections require a strict match of fields.
+      // If true and the same fields aren't present in both source and sink, a MissingFieldException,
+      // MissingLeftFieldException, or MissingRightFieldException will be thrown.
+      val connectFieldsMustMatch: Boolean
+      // When creating an object that takes a type argument, the argument must be unbound (a pure type).
+      val declaredTypeMustBeUnbound: Boolean
+      // Module IOs should be wrapped in an IO() to define their bindings before the reset of the module is defined.
+      val requireIOWrap: Boolean
+      // If a connection operator fails, don't try the connection with the operands (source and sink) reversed.
+      val dontTryConnectionsSwapped: Boolean
+      // If connection directionality is not explicit, do not use heuristics to attempt to determine it.
+      val dontAssumeDirectionality: Boolean
+      // Issue a deprecation warning if Data.{flip, asInput,asOutput} is used
+      // instead of Flipped, Input, or Output.
+      val deprecateOldDirectionMethods: Boolean
+      // Check that referenced Data have actually been declared.
+      val checkSynthesizable: Boolean
+    }
+```
+
+`chisel3.core.ExplicitCompileOptions.Strict` sets all CompileOptions fields to true and
+`chisel3.core.ExplicitCompileOptions.NotStrict` sets them all to false.
+Clients are free to define their own settings for these options.
+Examples may be found in the test [CompileOptionsSpec](https://github.com/ucb-bar/chisel3/blob/master/src/test/scala/chiselTests/CompileOptionsTest.scala)
diff --git a/docs/src/appendix/experimental-features.md b/docs/src/appendix/experimental-features.md
new file mode 100644
index 00000000..ba1a028d
--- /dev/null
+++ b/docs/src/appendix/experimental-features.md
@@ -0,0 +1,138 @@
+---
+layout: docs
+title:  "Experimental Features"
+section: "chisel3"
+---
+
+Chisel has a number of new features that are worth checking out.  This page is an informal list of these features and projects.
+
+### FixedPoint
+FixedPoint numbers are basic *Data* type along side of UInt, SInt, etc.  Most common math and logic operations
+are supported. Chisel allows both the width and binary point to be inferred by the Firrtl compiler which can simplify
+circuit descriptions. See [FixedPointSpec](https://github.com/freechipsproject/chisel3/tree/master/src/test/scala/chiselTests/FixedPointSpec.scala)
+
+### Module Variants
+The standard Chisel *Module* requires a `val io = IO(...)`, the experimental package introduces several
+new ways of defining Modules
+- BaseModule: no contents, instantiable
+- BlackBox extends BaseModule
+- UserDefinedModule extends BaseModule: this module can contain Chisel RTL. No default clock or reset lines. No default IO. - User should be able to specify non-io ports, ideally multiple of them.
+- ImplicitModule extends UserModule: has clock, reset, and io, essentially current Chisel Module.
+- RawModule: will be the user-facing version of UserDefinedModule
+- Module: type-aliases to ImplicitModule, the user-facing version of ImplicitModule.
+
+### Bundle Literals
+
+Bundle literals can be constructed via an experimental import:
+
+```scala mdoc
+import chisel3._
+import chisel3.experimental.BundleLiterals._
+
+class MyBundle extends Bundle {
+  val a = UInt(8.W)
+  val b = Bool()
+}
+
+class Example extends RawModule {
+  val out = IO(Output(new MyBundle))
+  out := (new MyBundle).Lit(_.a -> 8.U, _.b -> true.B)
+}
+```
+
+```scala mdoc:verilog
+chisel3.stage.ChiselStage.emitVerilog(new Example)
+```
+
+Partial specification is allowed, defaulting any unconnected fields to 0 (regardless of type).
+
+```scala mdoc
+class Example2 extends RawModule {
+  val out = IO(Output(new MyBundle))
+  out := (new MyBundle).Lit(_.b -> true.B)
+}
+```
+
+```scala mdoc:verilog
+chisel3.stage.ChiselStage.emitVerilog(new Example2)
+```
+
+Bundle literals can also be nested arbitrarily.
+
+```scala mdoc
+class ChildBundle extends Bundle {
+  val foo = UInt(8.W)
+}
+
+class ParentBundle extends Bundle {
+  val a = UInt(8.W)
+  val b = new ChildBundle
+}
+
+class Example3 extends RawModule {
+  val out = IO(Output(new ParentBundle))
+  out := (new ParentBundle).Lit(_.a -> 123.U, _.b -> (new ChildBundle).Lit(_.foo -> 42.U))
+}
+```
+
+```scala mdoc:verilog
+chisel3.stage.ChiselStage.emitVerilog(new Example3)
+```
+
+Vec literals are not yet supported.
+
+### Interval Type
+
+**Intervals** are a new experimental numeric type that comprises UInt, SInt and FixedPoint numbers.
+It augments these types with range information, i.e. upper and lower numeric bounds.
+This information can be used to exercise tighter programmatic control over the ultimate widths of
+signals in the final circuit.  The **Firrtl** compiler can infer this range information based on
+operations and earlier values in the circuit. Intervals support all the ordinary bit and arithmetic operations
+associated with UInt, SInt, and FixedPoint and adds the following methods for manipulating the range of
+a **source** Interval with the IntervalRange of **target** Interval
+
+#### Clip -- Fit the value **source** into the IntervalRange of **target**, saturate if out of bounds
+The clip method applied to an interval creates a new interval based on the argument to clip,
+and constructs the necessary hardware so that the source Interval's value will be mapped into the new Interval.
+Values that are outside the result range will be pegged to either maximum or minimum of result range as appropriate.
+
+> Generates necessary hardware to clip values, values greater than range are set to range.high, values lower than range are set to range min.
+
+#### Wrap -- Fit the value **source** into the IntervalRange of **target**, wrapping around if out of bounds
+The wrap method applied to an interval creates a new interval based on the argument to wrap,
+and constructs the necessary
+hardware so that the source Interval's value will be mapped into the new Interval.
+Values that are outside the result range will be wrapped until they fall within the result range.
+
+> Generates necessary hardware to wrap values, values greater than range are set to range.high, values lower than range are set to range min.
+
+> Does not handle out of range values that are less than half the minimum or greater than twice maximum
+
+#### Squeeze -- Fit the value **source** into the smallest IntervalRange based on source and target.
+The squeeze method applied to an interval creates a new interval based on the argument to clip, the two ranges must overlap
+behavior of squeeze with inputs outside of the produced range is undefined.
+
+> Generates no hardware, strictly a sizing operation
+
+##### Range combinations
+
+| Condition | A.clip(B) | A.wrap(B) | A.squeeze(B) |
+| --------- | --------------- | --------------- | --------------- |
+| A === B   | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  |
+| A contains B   | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  |
+| B contains A   | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  |
+| A min < B min, A max in B  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  |
+| A min in B, A max > B max  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  |
+| A strictly less than B   | error               | error               | error               |
+| A strictly greater than B   | error               | error               | error               |
+
+
+#### Applying binary point operators to an Interval
+
+Consider a Interval with a binary point of 3: aaa.bbb
+
+| operation | after operation | binary point | lower | upper | meaning |
+| --------- | --------------- | ------------ | ----- | ----- | ------- |
+| setBinaryPoint(2) | aaa.bb |  2 | X | X  | set the precision |
+| shiftLeftBinaryPoint(2) | a.aabbb |  5 | X | X  | increase the precision |
+| shiftRighBinaryPoint(2) | aaaa.b |  1 | X | X  | reduce the precision |
diff --git a/docs/src/appendix/upgrading-from-scala-2-11.md b/docs/src/appendix/upgrading-from-scala-2-11.md
new file mode 100644
index 00000000..26e2d252
--- /dev/null
+++ b/docs/src/appendix/upgrading-from-scala-2-11.md
@@ -0,0 +1,88 @@
+---
+layout: docs
+title:  "Upgrading From Scala 2.11"
+section: "chisel3"
+redirect_from:
+  - /chisel3/upgrading-from-scala-2-11.html
+---
+
+<!-- Prelude -->
+```scala mdoc:invisible
+import chisel3._
+```
+<!-- End Prelude -->
+
+## Upgrading From Scala 2.11 to 2.12
+
+As the latest (and probably last) release of Scala 2.11 (2.11.12) was released on 2 November 2017, the time has come to deprecate support for Scala 2.11.
+Chisel 3.4 is the last version of Chisel that will support Scala 2.11, so users should upgrade to Scala 2.12
+This document is intended to help guide Chisel users through this process; both the "Why?" and the "How?".
+
+### Scala Versioning
+
+<!-- TODO, this should be discussed in a different document about "Building Chisel" or something-->
+
+Scala versions have the following structure: `2.X.Y` where `X` is the _major version_ and `Y` is the _minor version_.
+Note that while we keep the leading `2` constant, there is a project, [Dotty](https://dotty.epfl.ch/), that is slated to become Scala 3.
+
+Scala maintains both source and binary compatiblity between minor versions, but not between major versions.
+Binary compatibility is defined at the level of the Java Byte Code (the `.class` or `.jar` files compiled from `.scala`).
+This means that Scala projects that support multiple major versions of Scala must be compiled and published for each supported version.
+When publishing artifacts to Maven repositories, this manifests as an appendix on the _Artifact ID_.
+Taking Chisel v3.3.2 as an example, the "Artifact ID" is ["chisel3_2.12"](https://search.maven.org/artifact/edu.berkeley.cs/chisel3_2.12)
+for Scala 2.12, and ["chisel3_2.11"](https://search.maven.org/artifact/edu.berkeley.cs/chisel3_2.11) for Scala 2.11.
+
+For more information, see the documentation on the Scala website:
+* [Binary Compatibility of Scala Releases](https://docs.scala-lang.org/overviews/core/binary-compatibility-of-scala-releases.html)
+* [Binary Compatibility for Library Authoers](https://docs.scala-lang.org/overviews/core/binary-compatibility-for-library-authors.html)
+
+
+### How to Upgrade
+
+For most users, this is as simple as changing the `scalaVersion` field in your `build.sbt`:
+```scala
+scalaVersion := "2.11.12"
+```
+Becomes
+```scala
+scalaVersion := "2.12.12"
+```
+Now, the next time you run SBT, it will be using the Scala 2.12 version of Chisel 3 (as well as any other dependencies you have).
+
+### Common Issues
+
+As mentioned in the [previous section](#scala-versioning), Scala does *not* maintain source compatibilty between major versions.
+Put another way, sometimes they break things in backwards incompatible ways.
+This section includes some common issues that Chisel users run into and how to fix them.
+
+For complete information about changes, please see the [release notes for Scala 2.12.0](https://www.scala-lang.org/news/2.12.0/).
+
+#### Value is not a member of chisel3.Bundle
+
+The most common problem for Chisel users upgrading from Scala 2.11 to 2.12 is a change in Scala type inference.
+This usually occurs in the context of `io` `Bundles` in `Modules`, given:
+```scala mdoc:silent
+class Foo extends Module {
+  val io = IO(new Bundle {
+    val in = Input(Bool())
+    val out = Output(Bool())
+  })
+
+  io.out := ~io.in
+}
+```
+You may see an error that says somethign like "value out is not a member of chisel3.Bundle":
+```
+[error] /workspace/src/main/scala/gcd/Foo.scala:9:6: value out is not a member of chisel3.Bundle
+[error]   io.out := ~io.in
+[error]      ^
+[error] /workspace/src/main/scala/gcd/Foo.scala:9:17: value in is not a member of chisel3.Bundle
+[error]   io.out := ~io.in
+[error]                 ^
+[error] two errors found
+```
+This can be worked around by adding `-Xsource:2.11` to your `scalacOptions`.
+This is most commonly set in your `build.sbt`.
+For an example, see the [chisel-template's build.sbt](https://github.com/freechipsproject/chisel-template/blob/11f6ca470120908d167cb8dc3241953eb31d0acb/build.sbt#L10).
+
+