An incomplete, early, and in-progress overview of the language design.

docs/design/aliases.md

@@ -0,0 +1,49 @@
+# Aliases
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+## Table of contents
+
+<!-- toc -->
+
+- [TODO](#todo)
+- [Overview](#overview)
+  - [Alternatives](#alternatives)
+
+<!-- tocstop -->
+
+## TODO
+
+This is a skeletal design, added to support [the overview](README.md). It should
+not be treated as accepted by the core team; rather, it is a placeholder until
+we have more time to examine this detail. Please feel welcome to rewrite and
+update as appropriate.
+
+## Overview
+
+Naming is one of the things that most often requires careful management over
+time -- things tend to get renamed and moved around.
+
+Carbon provides a fully general name aliasing facility to declare a new name as
+an alias for a value; everything is a value in Carbon. This is a fully general
+facility because everything is a value in Carbon, including types.
+
+For example:
+
+```
+alias MyInt = Int;
+```
+
+This creates an alias called `MyInt` for whatever `Int` resolves to. Code
+textually after this can refer to `MyInt`, and it will transparently refer to
+`Int`.
+
+### Alternatives
+
+The syntax here is not at all in a good state yet. We've considered a few
+alternatives, but they all end up being confusing in some way. We need to figure
+out a good and clean syntax that can be used here.

docs/design/blocks_and_statements.md

@@ -0,0 +1,51 @@
+# Blocks and statements
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+## Table of contents
+
+<!-- toc -->
+
+- [TODO](#todo)
+- [Overview](#overview)
+
+<!-- tocstop -->
+
+## TODO
+
+This is a skeletal design, added to support [the overview](README.md). It should
+not be treated as accepted by the core team; rather, it is a placeholder until
+we have more time to examine this detail. Please feel welcome to rewrite and
+update as appropriate.
+
+## Overview
+
+The body or definition of a function is provided by a block of code containing
+statements, much like in C or C++. The body of a function is also a new, nested
+scope inside the function's scope (meaning that parameter names are available).
+Statements within a block are terminated by a semicolon. Each statement can,
+among other things, be an expression. Here is a trivial example of a function
+definition using a block of statements:
+
+```
+fn Foo() {
+  Bar();
+  Baz();
+}
+```
+
+Statements can also themselves be a block of statements, which provide scopes
+and nesting:
+
+```
+fn Foo() {
+  Bar();
+  {
+    Baz();
+  }
+}
+```

docs/design/control_flow.md

@@ -0,0 +1,80 @@
+# Control flow
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+## Table of contents
+
+<!-- toc -->
+
+- [TODO](#todo)
+- [Overview](#overview)
+- [Open questions](#open-questions)
+  - [`if` blocks](#if-blocks)
+  - [`break` and `continue`](#break-and-continue)
+
+<!-- tocstop -->
+
+## TODO
+
+This is a skeletal design, added to support [the overview](README.md). It should
+not be treated as accepted by the core team; rather, it is a placeholder until
+we have more time to examine this detail. Please feel welcome to rewrite and
+update as appropriate.
+
+At least summarize `if` and `else` to cover basics. Especially important to
+surface the idea of using basic conditionals as both expressions and statements
+to avoid needing conditional operators.
+
+Looping is an especially interesting topic to explore as there are lots of
+challenges posed by the C++ loop structure. Even C++ itself has been seeing
+significant interest and pressure to improve its looping facilities.
+
+## Overview
+
+Blocks of statements are generally executed linearly. However, statements are
+the primary place where this flow of execution can be controlled. Carbon's
+control flow constructs are mostly similar to those in C, C++, and other
+languages.
+
+```
+fn Foo(Int: x) {
+  if (x < 42) {
+    Bar();
+  } else if (x > 77) {
+    Baz();
+  }
+}
+```
+
+Loops will at least be supported with a low-level primitive `loop` statement,
+with `break` and `continue` statements which work the same as in C++.
+
+Last but not least, for the basics we need to include the `return` statement.
+This statement ends the flow of execution within a function, returning it to the
+caller. If the function returns a value to the caller, that value is provided by
+an expression in the return statement. This allows us to complete the definition
+of our `Sum` function from earlier as:
+
+```
+fn Sum(Int: a, Int: b) -> Int {
+  return a + b;
+}
+```
+
+## Open questions
+
+### `if` blocks
+
+It is an open question whether a block is required or a single statement may be
+nested in an `if` statement. Similarly, it is an open question whether `else if`
+is a single keyword versus a nested `if` statement, and if it is a single
+construct whether it should be spelled `elif` or something else.
+
+### `break` and `continue`
+
+If and how to support a "labeled break" or "labeled continue" is still a point
+of open discussion.

docs/design/files_libraries_and_packages.md

@@ -0,0 +1,43 @@
+# Files, libraries, and packages
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+## Table of contents
+
+<!-- toc -->
+
+- [TODO](#todo)
+- [Alternatives](#alternatives)
+  - [File extensions](#file-extensions)
+
+<!-- tocstop -->
+
+## TODO
+
+This is a skeletal design, added to support [the overview](README.md). It should
+not be treated as accepted by the core team; rather, it is a placeholder until
+we have more time to examine this detail. Please feel welcome to rewrite and
+update as appropriate.
+
+## Alternatives
+
+### File extensions
+
+The use of `6c` as a short file extension or top-level CLI (with subcommands
+below it similar to `git` or `go`) has some drawbacks. There are several other
+possible extensions / commands:
+
+- `cb`: This collides with several acronyms and may not be especially memorable
+  as referring to Carbon.
+- `c6`: This seems a weird incorrect ordering of the atomic number and has a bad
+  (if _extremely_ obscure) Internet slang association (NSFW, use caution if
+  searching, as with too much Internet slang).
+- `carbon`: This is an obvious and unsurprising choice, but also quite long.
+
+This seems fairly easy for us to change as we go along, but we should at some
+point do a formal proposal to gather other options and let the core team try to
+find the set that they feel is close enough to be a bikeshed.

docs/design/functions.md

@@ -0,0 +1,63 @@
+# Functions
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+## Table of contents
+
+<!-- toc -->
+
+- [TODO](#todo)
+- [Basic functions](#basic-functions)
+
+<!-- tocstop -->
+
+## TODO
+
+This is a skeletal design, added to support [the overview](README.md). It should
+not be treated as accepted by the core team; rather, it is a placeholder until
+we have more time to examine this detail. Please feel welcome to rewrite and
+update as appropriate.
+
+## Basic functions
+
+Programs written in Carbon, much like those written in other languages, are
+primarily divided up into "functions" (or "procedures", "subroutines", or
+"subprograms"). These are the core unit of behavior for the programming
+language. Let's look at a simple example to understand how these work:
+
+```
+fn Sum(Int: a, Int: b) -> Int;
+```
+
+This declares a function called `Sum` which accepts two `Int` parameters, the
+first called `a` and the second called `b`, and returns an `Int` result. C++
+might declare the same thing:
+
+```
+std::int64_t Sum(std::int64_t a, std::int64_t b);
+
+// Or with trailing return type syntax:
+auto Sum(std::int64_t a, std::int64_t b) -> std::int64_t;
+```
+
+Let's look at how some specific parts of this work. The function declaration is
+introduced with a keyword `fn` followed by the name of the function `Sum`. This
+declares that name in the surrounding scope and opens up a new scope for this
+function. We declare the first parameter as `Int: a`. The `Int` part is an
+expression (here referring to a constant) that computes the type of the
+parameter. The `:` marks the end of the type expression and introduces the
+identifier for the parameter, `a`. The parameter names are introduced into the
+function's scope and can be referenced immediately after they are introduced.
+The return type is indicated with `-> Int`, where again `Int` is just an
+expression computing the desired type. The return type can be completely omitted
+in the case of functions which do not return a value.
+
+Calling functions involves a new form of expression: `Sum(1, 2)` for example.
+The first part, `Sum`, is an expression referring to the name of the function.
+The second part, `(1, 2)` is a parenthesized list of arguments to the function.
+The juxtaposition of one expression with parentheses forms the core of a call
+expression, similar to a postfix operator.

docs/design/interoperability/template.md

@@ -0,0 +1,28 @@
+# Carbon ↔ C/C++ interoperability
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+## Table of contents
+
+<!-- toc -->
+
+- [TODO](#todo)
+- [Overview](#overview)
+
+<!-- tocstop -->
+
+## TODO
+
+This is a skeletal design, added to support [the overview](README.md). It should
+not be treated as accepted by the core team; rather, it is a placeholder until
+we have more time to examine this detail. Please feel welcome to rewrite and
+update as appropriate.
+
+## Overview
+
+See the draft in
+[PR 80](https://github.com/carbon-language/carbon-lang/pull/80).

docs/design/lexical_conventions.md

@@ -0,0 +1,25 @@
+# Lexical conventions
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+## Table of contents
+
+<!-- toc -->
+
+- [TODO](#todo)
+
+<!-- tocstop -->
+
+## TODO
+
+This is a skeletal design, added to support [the overview](README.md). It should
+not be treated as accepted by the core team; rather, it is a placeholder until
+we have more time to examine this detail. Please feel welcome to rewrite and
+update as appropriate.
+
+See [PR 17](https://github.com/carbon-language/carbon-lang/pull/17) for context
+-- that proposal may replace this.

docs/design/metaprogramming.md

@@ -0,0 +1,33 @@
+# Metaprogramming
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+## Table of contents
+
+<!-- toc -->
+
+- [TODO](#todo)
+- [Overview](#overview)
+
+<!-- tocstop -->
+
+## TODO
+
+This is a skeletal design, added to support [the overview](README.md). It should
+not be treated as accepted by the core team; rather, it is a placeholder until
+we have more time to examine this detail. Please feel welcome to rewrite and
+update as appropriate.
+
+See
+[carbon-proposals PR 89](https://github.com/carbon-language/carbon-proposals/pull/89)
+for context -- that proposal may replace this.
+
+## Overview
+
+Carbon provides metaprogramming facilities that look similar to regular Carbon
+code. These are structured, and do not offer inclusion or arbitrary
+preprocessing of source text such as C/C++ does.