Port old site to dottydoc

19 files changed, 177 insertions, 48 deletions

diff --git a/docs/docs/contributing/eclipse.md b/docs/docs/contributing/eclipse.md
index 0e4125df0..a7deab804 100644
--- a/docs/docs/contributing/eclipse.md
+++ b/docs/docs/contributing/eclipse.md
@@ -1,6 +1,6 @@
 ---
-layout: default
-title: "Building Dotty with Eclipse"
+layout: doc-page
+title: Building Dotty with Eclipse
 ---
 
 Build setup
diff --git a/docs/docs/contributing/getting-started.md b/docs/docs/contributing/getting-started.md
index 4c7299914..e38c3a8fc 100644
--- a/docs/docs/contributing/getting-started.md
+++ b/docs/docs/contributing/getting-started.md
@@ -1,6 +1,6 @@
 ---
-layout: default
-title: "Getting Started"
+layout: doc-page
+title: Getting Started
 ---
 
 Talks on Dotty
diff --git a/docs/docs/contributing/intellij-idea.md b/docs/docs/contributing/intellij-idea.md
index 9231f209a..5f477bef8 100644
--- a/docs/docs/contributing/intellij-idea.md
+++ b/docs/docs/contributing/intellij-idea.md
@@ -1,6 +1,6 @@
 ---
-layout: default
-title: "Building Dotty with Intellij IDEA"
+layout: doc-page
+title: Building Dotty with Intellij IDEA
 ---
 
 Dotty compiler support is available in the [Scala plugin nightly] starting
diff --git a/docs/docs/contributing/workflow.md b/docs/docs/contributing/workflow.md
index fb8da0da3..6e7f5b9a0 100644
--- a/docs/docs/contributing/workflow.md
+++ b/docs/docs/contributing/workflow.md
@@ -1,6 +1,6 @@
 ---
-layout: default
-title: "Workflow"
+layout: doc-page
+title: Workflow
 ---
 
 This document details common workflow patterns when working with Dotty.
@@ -19,13 +19,14 @@ git clone -b dotty-library https://github.com/DarkDimius/scala.git scala-scala
 
 From sbt:
 
-```none
+```bash
+$ sbt
 > dotc <OPTIONS> <FILE>
 ```
 
 From terminal:
 
-```none
+```bash
 $ ./bin/dotc <OPTIONS> <FILE>
 ```
 
@@ -47,7 +48,7 @@ Additional logging information can be obtained by changes some `noPrinter` to
 
 ## Running tests ##
 
-```none
+```bash
 $ sbt
 > partest --show-diff --verbose
 ```
@@ -55,7 +56,7 @@ $ sbt
 ## Running single tests ##
 To test a specific test tests/x/y.scala (for example tests/pos/t210.scala):
 
-```none
+```bash
 > partest-only-no-bootstrap --show-diff --verbose tests/partest-generated/x/y.scala
 ```
 
@@ -67,7 +68,7 @@ the way partest has been set up.
 There is no power mode for the REPL yet, but you can inspect types with the
 type stealer:
 
-```none
+```bash
 > repl
 scala> import dotty.tools.DottyTypeStealer._; import dotty.tools.dotc.core._; import Contexts._,Types._
 ```
diff --git a/docs/docs/index.md b/docs/docs/index.md
index 0d9bc6b6f..4ee381812 100644
--- a/docs/docs/index.md
+++ b/docs/docs/index.md
@@ -1,5 +1,5 @@
 ---
-layout: default
+layout: doc-page
 title: "Dotty Documentation"
 ---
 
diff --git a/docs/docs/internals/backend.md b/docs/docs/internals/backend.md
index 47974b5ff..e1fd20da2 100644
--- a/docs/docs/internals/backend.md
+++ b/docs/docs/internals/backend.md
@@ -1,5 +1,5 @@
 ---
-layout: default
+layout: doc-page
 title: "Backend Internals"
 ---
 
@@ -33,18 +33,19 @@ BCodeIdiomatic     ---------------->        utilities for code generation, e.g.
 
 ### Data Flow ###
 Compiler creates a `BCodePhase`, calls `runOn(compilationUnits)`.
-  * initializes fields of `GenBCode` defined in `BCodeTypes` (BType maps,
-    common BTypes like `StringReference`)
-  * initialize `primitives` map defined in `scalaPrimitives` (maps primitive
-    members, like `int.+`, to bytecode instructions)
-  * creates `BytecodeWriter`, `JMirrorBuilder` and `JBeanInfoBuilder` instances
-    (on each compiler run)
-  * `buildAndSendToDisk(units)`: uses work queues, see below.
-    - `BCodePhase.addToQ1` adds class trees to `q1`
-    - `Worker1.visit` creates ASM `ClassNodes`, adds to `q2`. It creates one
-      `PlainClassBuilder` for each compilation unit.
-    - `Worker2.addToQ3` adds byte arrays (one for each class) to `q3`
-    - `BCodePhase.drainQ3` writes byte arrays to disk
+
+* initializes fields of `GenBCode` defined in `BCodeTypes` (BType maps,
+  common BTypes like `StringReference`)
+* initialize `primitives` map defined in `scalaPrimitives` (maps primitive
+  members, like `int.+`, to bytecode instructions)
+* creates `BytecodeWriter`, `JMirrorBuilder` and `JBeanInfoBuilder` instances
+  (on each compiler run)
+* `buildAndSendToDisk(units)`: uses work queues, see below.
+  - `BCodePhase.addToQ1` adds class trees to `q1`
+  - `Worker1.visit` creates ASM `ClassNodes`, adds to `q2`. It creates one
+    `PlainClassBuilder` for each compilation unit.
+  - `Worker2.addToQ3` adds byte arrays (one for each class) to `q3`
+  - `BCodePhase.drainQ3` writes byte arrays to disk
 
 
 ### Architecture ###
diff --git a/docs/docs/internals/benchmarks.md b/docs/docs/internals/benchmarks.md
index 4d24ec0ff..f2ddbd6d0 100644
--- a/docs/docs/internals/benchmarks.md
+++ b/docs/docs/internals/benchmarks.md
@@ -1,5 +1,10 @@
+---
+layout: doc-page
+title: "Benchmarks"
+---
+
 The regression benchmark infrastructure is still under construction.
 
 A preview can be found below:
 
-- [d-d.me/tnc/dotty/web/](https://d-d.me/tnc/dotty/web/)
\ No newline at end of file
+- [d-d.me/tnc/dotty/web/](https://d-d.me/tnc/dotty/web/)
diff --git a/docs/docs/internals/classpaths.md b/docs/docs/internals/classpaths.md
index 0038b5de0..1a137c1ea 100644
--- a/docs/docs/internals/classpaths.md
+++ b/docs/docs/internals/classpaths.md
@@ -1,3 +1,8 @@
+---
+layout: doc-page
+title: Classpaths
+---
+
 When ran from the `dotty` script, this is the classloader stack:
 
 ```
diff --git a/docs/docs/internals/contexts.md b/docs/docs/internals/contexts.md
index 09cbb40c5..df998d49b 100644
--- a/docs/docs/internals/contexts.md
+++ b/docs/docs/internals/contexts.md
@@ -1,6 +1,6 @@
 ---
-layout: default
-title: "Contexts"
+layout: doc-page
+title: Contexts
 ---
 
 The `Context` contains the state of the compiler, for example
diff --git a/docs/docs/internals/core-data-structures.md b/docs/docs/internals/core-data-structures.md
new file mode 100644
index 000000000..623114aa3
--- /dev/null
+++ b/docs/docs/internals/core-data-structures.md
@@ -0,0 +1,117 @@
+---
+layout: doc-page
+title: Core Data Structures
+---
+
+(The following is work in progress)
+
+## Symbols and SymDenotations
+
+ - why symbols are not enough: their contents change all the time
+ - they change themselvesSo a `Symbol`
+ - reference: string + sig
+
+
+Dotc is different from most other compilers in that it is centered around the idea of
+maintaining views of various artifacts associated with code. These views are indexed
+by tne
+
+A symbol refers to a definition in a source program. Traditionally,
+ compilers store context-dependent data in a _symbol table_. The
+ symbol then is the central reference to address context-dependent
+ data. But for `dotc`'s requirements it turns out that symbols are
+ both too little and too much for this task.
+
+Too little: The attributes of a symbol depend on the phase. Examples:
+Types are gradually simplified by several phases. Owners are changed
+in phases `LambdaLift` (when methods are lifted out to an enclosing
+class) and Flatten (when all classes are moved to top level). Names
+are changed when private members need to be accessed from outside
+their class (for instance from a nested class or a class implementing
+a trait). So a functional compiler, a `Symbol` by itself met mean
+much. Instead we are more interested in the attributes of a symbol at
+a given phase.
+
+`dotc` has a concept for "attributes of a symbol at
+
+Too much: If a symbol is used to refer to a definition in another
+compilation unit, we get problems for incremental recompilation. The
+unit containing the symbol might be changed and recompiled, which
+might mean that the definition referred to by the symbol is deleted or
+changed. This leads to the problem of stale symbols that refer to
+definitions that no longer exist in this form. `scalac` tried to
+address this problem by _rebinding_ symbols appearing in certain cross
+module references, but it turned out to be too difficult to do this
+reliably for all kinds of references. `dotc` attacks the problem at
+the root instead. The fundamental problem is that symbols are too
+specific to serve as a cross-module reference in a system with
+incremental compilation. They refer to a particular definition, but
+that definition may not persist unchanged after an edit.
+
+`dotc` uses instead a different approach: A cross module reference is
+always type, either a `TermRef` or ` TypeRef`. A reference type contains
+a prefix type and a name. The definition the type refers to is established
+dynamically based on these fields.
+
+
+a system where sources can be recompiled at any instance,
+
+ the concept of a `Denotation`.
+
+ Since definitions are transformed by phases,
+
+
+The [Dotty project](https://github.com/lampepfl/dotty)
+is a platform to develop new technology for Scala
+tooling and to try out concepts of future Scala language versions.
+Its compiler is a new design intended to reflect the
+lessons we learned from work with the Scala compiler. A clean redesign
+today will let us iterate faster with new ideas in the future.
+
+Today we reached an important milestone: The Dotty compiler can
+compile itself, and the compiled compiler can act as a drop-in for the
+original one. This is what one calls a *bootstrap*.
+
+## Why is this important?
+
+The main reason is that this gives us a some validation of the
+*trustworthiness* of the compiler itself. Compilers are complex beasts,
+and many things can go wrong. By far the worst things that can go
+wrong are bugs where incorrect code is produced. It's not fun debugging code that looks perfectly
+fine, yet gets translated to something subtly wrong by the compiler.
+
+Having the compiler compile itself is a good test to demonstrate that
+the generated code has reached a certain level of quality. Not only is
+a compiler a large program (44k lines in the case of dotty), it is
+also one that exercises a large part of the language in quite
+intricate ways. Moreover, bugs in the code of a compiler don't tend to
+go unnoticed, precisely because every part of a compiler feeds into
+other parts and all together are necessary to produce a correct
+translation.
+
+## Are We Done Yet?
+
+Far from it! The compiler is still very rough. A lot more work is
+needed to
+
+ - make it more robust, in particular when analyzing incorrect programs,
+ - improve error messages and warnings,
+ - improve the efficiency of some of the generated code,
+ - embed it in external tools such as sbt, REPL, IDEs,
+ - remove restrictions on what Scala code can be compiled,
+ - help in migrating Scala code that will have to be changed.
+
+## What Are the Next Steps?
+
+Over the coming weeks and months, we plan to work on the following topics:
+
+ - Make snapshot releases.
+ - Get the Scala standard library to compile.
+ - Work on SBT integration of the compiler.
+ - Work on IDE support.
+ - Investigate the best way to obtaining a REPL.
+ - Work on the build infrastructure.
+
+If you want to get your hands dirty with any of this, now is a good moment to get involved!
+To get started: <https://github.com/lampepfl/dotty>.
+
diff --git a/docs/docs/internals/dotc-scalac.md b/docs/docs/internals/dotc-scalac.md
index f41f21370..9a7de2cb9 100644
--- a/docs/docs/internals/dotc-scalac.md
+++ b/docs/docs/internals/dotc-scalac.md
@@ -1,5 +1,5 @@
 ---
-layout: default
+layout: doc-page
 title: "Differences between Scalac and Dotty"
 ---
 
diff --git a/docs/docs/internals/higher-kinded-v2.md b/docs/docs/internals/higher-kinded-v2.md
index 3019e3031..4676d3ebd 100644
--- a/docs/docs/internals/higher-kinded-v2.md
+++ b/docs/docs/internals/higher-kinded-v2.md
@@ -1,5 +1,5 @@
 ---
-layout: default
+layout: doc-page
 title: "Higher-Kinded Types in Dotty"
 ---
 
diff --git a/docs/docs/internals/overall-structure.md b/docs/docs/internals/overall-structure.md
index 1b4e22f1b..78cc26c8d 100644
--- a/docs/docs/internals/overall-structure.md
+++ b/docs/docs/internals/overall-structure.md
@@ -1,5 +1,5 @@
 ---
-layout: default
+layout: doc-page
 title: "Dotty Overall Structure"
 ---
 
diff --git a/docs/docs/internals/periods.md b/docs/docs/internals/periods.md
index bb161b7b8..257d8504e 100644
--- a/docs/docs/internals/periods.md
+++ b/docs/docs/internals/periods.md
@@ -1,5 +1,5 @@
 ---
-layout: default
+layout: doc-page
 title: "Dotc's concept of time"
 ---
 
diff --git a/docs/docs/internals/syntax.md b/docs/docs/internals/syntax.md
index 7c8cb1ea2..b7d5936c2 100644
--- a/docs/docs/internals/syntax.md
+++ b/docs/docs/internals/syntax.md
@@ -1,5 +1,5 @@
 ---
-layout: default
+layout: doc-page
 title: "Scala Syntax Summary"
 ---
 
diff --git a/docs/docs/internals/type-system.md b/docs/docs/internals/type-system.md
index e3a563c21..eda1cfbde 100644
--- a/docs/docs/internals/type-system.md
+++ b/docs/docs/internals/type-system.md
@@ -1,5 +1,5 @@
 ---
-layout: default
+layout: doc-page
 title: "Type System"
 ---
 
diff --git a/docs/docs/usage/cbt-projects.md b/docs/docs/usage/cbt-projects.md
index 291813b91..d4915fe39 100644
--- a/docs/docs/usage/cbt-projects.md
+++ b/docs/docs/usage/cbt-projects.md
@@ -1,5 +1,5 @@
 ---
-layout: default
+layout: doc-page
 title: "Using Dotty with cbt"
 ---
 
@@ -9,7 +9,7 @@ cbt comes with built-in dotty support. Follow the
 ```scala
 // build/build.scala
 import cbt._
-class Build(val context: Context) extends Dotty{
+class Build(val context: Context) extends Dotty {
   ...
 }
 ```
diff --git a/docs/docs/usage/migrating.md b/docs/docs/usage/migrating.md
index eb76571e5..5a2f64be3 100644
--- a/docs/docs/usage/migrating.md
+++ b/docs/docs/usage/migrating.md
@@ -1,5 +1,5 @@
 ---
-layout: default
+layout: doc-page
 title: "Migrating to Dotty"
 ---
 
@@ -17,15 +17,15 @@ Most `sym.isProperty` methods don't exist in dotc, test for flags instead. See
 [dotc vs scalac: Trees, Symbols, Types & Denotations]
 
 ### Logging, Error Reporting, Failures ###
-
 There are various kinds of logging:
-  * Errors, warnings, etc: `ctx.inform`, `ctx.warning`, `ctx.error`, ...
-  * Log messages displayed under `-Ylog:phase`: `log(msg)` in scalac =>
-    `ctx.log(msg)` in dotc
-  * Debug-Log messages displayed under `-Ydebug -Ylog:<phase>`: `debuglog(msg)`
-    in scalac => `ctx.debuglog(msg)` in dotc
-  * Assertions: `assert(invariant)`
-  * Fatal errors: `abort(msg)` in scalac => `throw new
+
+* Errors, warnings, etc: `ctx.inform`, `ctx.warning`, `ctx.error`, ...
+* Log messages displayed under `-Ylog:phase`: `log(msg)` in scalac =>
+  `ctx.log(msg)` in dotc
+* Debug-Log messages displayed under `-Ydebug -Ylog:<phase>`: `debuglog(msg)`
+  in scalac => `ctx.debuglog(msg)` in dotc
+* Assertions: `assert(invariant)`
+* Fatal errors: `abort(msg)` in scalac => `throw new
     dotty.tools.dotc.FatalError(msg)` in dotc
 
 
diff --git a/docs/docs/usage/sbt-projects.md b/docs/docs/usage/sbt-projects.md
index b4eb5136d..2f27492a7 100644
--- a/docs/docs/usage/sbt-projects.md
+++ b/docs/docs/usage/sbt-projects.md
@@ -1,5 +1,5 @@
 ---
-layout: default
+layout: doc-page
 title: "Using Dotty with sbt"
 ---