Expand comparisons section

Also add short anchor names to all subsections that don't already have them
And make anchor names all lowercase-like-this

Author: hsutter

Diff for: docs/cpp2/aliases.md

@@ -1,18 +1,18 @@
 # Aliases
 
-## Namespace aliases
+## <a id="namespace-aliases"></a> Namespace aliases
 
 TODO
 
-## Type aliases
+## <a id="type-aliases"></a> Type aliases
 
 TODO
 
-## Function aliases
+## <a id="function-aliases"></a> Function aliases
 
 TODO
 
-## Object aliases
+## <a id="object-aliases"></a> Object aliases
 
 TODO
 

Diff for: docs/cpp2/common.md

@@ -1,6 +1,6 @@
 # Common programming concepts
 
-## `main`
+## <a id="main"></a> `main`
 
 As always, `main` is the entry point of the program. For example:
 
@@ -39,7 +39,7 @@ main: (args) -> int
 - Some other type that your Cpp1 compiler(s) supports as a nonstandard extension.
 
 
-## Comments
+## <a id="comments"></a> Comments
 
 The usual `#!cpp // line comments` and `#!cpp /* stream comments */` are supported. For example:
 
@@ -55,7 +55,7 @@ The usual `#!cpp // line comments` and `#!cpp /* stream comments */` are support
 ```
 
 
-## Reserved keywords
+## <a id="keywords"></a> Reserved keywords
 
 Cpp2 has very few globally reserved keywords; nearly all keywords are contextual, where they have their special meaning when they appear in a particular place in the grammar. For example:
 
@@ -68,7 +68,7 @@ Cpp2 has very few globally reserved keywords; nearly all keywords are contextual
 In rare cases, usually when consuming code written in other languages, you may need to write a name that is a reserved keyword. The way to do that is to prefix it with `__identifer__`, which treats it as an ordinary identifier (without the prefix).
 
 
-## Fundamental data types
+## <a id="fundamental-types"></a> Fundamental data types
 
 Cpp2 supports the same fundamental types as today's Cpp1, but additionally provides the following aliases in namespace `cpp2`:
 
@@ -97,7 +97,7 @@ Cpp2 supports the same fundamental types as today's Cpp1, but additionally provi
 | `_schar`     | `#!cpp signed char`   | Normally, prefer `i8` instead |
 | `_uchar`     | `#!cpp unsigned char` | Normally, prefer `u8` instead |
 
-## Type qualifiers
+## <a id="type-qualifiers"></a> Type qualifiers
 
 Types can be qualified with `#!cpp const` and `#!cpp *`. Types are written left-to-right, so a qualifier always applies to what immediately follows it. For example, to declare a `#!cpp const` pointer to a non-`#!cpp const` pointer to a `#!cpp const i32` object, write:
 
@@ -106,7 +106,7 @@ Types can be qualified with `#!cpp const` and `#!cpp *`. Types are written left-
 p: const * * const i32;
 ```
 
-## Literals
+## <a id="literals"></a> Literals
 
 Cpp2 supports the same `#!cpp 'c'`haracter, `#!cpp "string"`, binary, integer, and floating point literals as Cpp1, including most Unicode encoding prefixes and raw string literals.
 
@@ -118,11 +118,11 @@ Cpp2 supports using Cpp1 user-defined literals for compatibility, to support sea
 
 Both **`123.nm()`** and **`123.u8()`** are very similar to user-defined literal syntax, and more general.
 
-## Operators
+## <a id="operators"></a> Operators
 
 Operators have the same precedence and associativity as in Cpp1, but some unary operators that are prefix (always or sometimes) in Cpp1 are postfix (always) in Cpp2.
 
-### Unary operators
+### <a id="unary-operators"></a> Unary operators
 
 The operators `!`, `+`, and `-` are prefix, as in Cpp1. For example:
 
@@ -178,7 +178,7 @@ Unary suffix operators must not be preceded by whitespace. When `*`, `&`, and `~
 For more details, see [Design note: Postfix unary operators vs binary operators](https://github.com/hsutter/cppfront/wiki/Design-note%3A-Postfix-unary-operators-vs-binary-operators).
 
 
-### Binary operators
+### <a id="binary-operators"></a> Binary operators
 
 Binary operators are the same as in Cpp1. From highest to lowest precedence:
 

Diff for: docs/cpp2/contracts.md

@@ -6,11 +6,11 @@
 TODO
 
 
-## Contract groups
+## <a id="contract-groups"></a> Contract groups
 
 TODO
 
 
-## Customizing the violation handler
+## <a id="violation-handlers"></a> Customizing the violation handler
 
 TODO

Diff for: docs/cpp2/declarations.md

@@ -1,6 +1,6 @@
 # Declaration syntax
 
-## Unified declaration syntax
+## Overview: Unified declaration syntax
 
 All Cpp2 declarations are written as **"_name_ `:` _kind_ `=` _statement_"**.
 
@@ -61,10 +61,10 @@ n: namespace
 }
 ```
 
-> Note: `@enum` is a metafunction, which provides an easy way to opt into a group of defaults, constraints, and generated functions. For details, see [`@enum`, `@flag_enum`](metafunctions.md/#enum-flag_enum)
+> Note: `@enum` is a metafunction, which provides an easy way to opt into a group of defaults, constraints, and generated functions. For details, see [`@enum`, `@flag_enum`](metafunctions.md#enum-flag_enum)
 
 
-## `requires` constraints
+## <a id="requires"></a> `requires` constraints
 
 TODO
 

Diff for: docs/cpp2/expressions.md

@@ -1,7 +1,7 @@
 
 # Common expressions
 
-## Calling functions: `f(x)` syntax, and `x.f()` UFCS syntax
+## <a id="ufcs"></a> Calling functions: `f(x)` syntax, and `x.f()` UFCS syntax
 
 A function call like `f(x)` is a normal function call that will call non-member functions only, as usual in C++.
 
@@ -41,13 +41,13 @@ To explicitly treat an object name passed as an argument as `move` or `out`, wri
 
 - Explicit `move` is rarely needed. Every definite last use of a local variable will apply `move` by default. Writing `move` from an object before its definite last use means that later uses may see a moved-from state.
 
-- Explicit `out` is needed only when initializing a local variable separately from its declaration using a call to a function with an `out` parameter. For details, see [Guaranteed initialization](../cpp2/objects.md#Init).
+- Explicit `out` is needed only when initializing a local variable separately from its declaration using a call to a function with an `out` parameter. For details, see [Guaranteed initialization](../cpp2/objects.md#init).
 
 For example:
 
 
 
-## `_` — the "don't care" wildcard, including explicit discard
+## <a id="wildcard"></a> `_` — the "don't care" wildcard, including explicit discard
 
 `_` is pronounced **"don't care"** and allowed as a wildcard in most contexts. For example:
 
@@ -84,7 +84,7 @@ _ = vec.emplace_back(1,2,3);
 For details, see [Design note: Explicit discard](https://github.com/hsutter/cppfront/wiki/Design-note%3A-Explicit-discard). In Cpp2, data is always initialized, data is never silently lost, data flow is always visible. Data is precious, and it's always safe.
 
 
-## `is` — safe type/value queries
+## <a id="is"></a> `is` — safe type/value queries
 
 An `x is C` expression allows safe type and value queries, and evaluates to `#!cpp true` if `x` matches constraint `C`. It supports both static and dynamic queries, including customization, with support for standard library dynamic types like `std::variant`, `std::optional`, `std::expected`, and `std::any` provided out of the box.
 
@@ -132,7 +132,7 @@ Here are some `is` queries with their Cpp1 equivalents. In this table, uppercase
 > Note: `is` unifies a variety of differently-named Cpp1 language and library queries under one syntax, and supports only the type-safe ones.
 
 
-## `as` — safe casts and conversions
+## <a id="as"></a> `as` — safe casts and conversions
 
 An `x as T` expression allows safe type casts. `x` must be an object or expression, and `T` must be a type. Like `is`, `as` supports both static and dynamic typing, including customization, with support for standard library dynamic types like `std::variant`, `std::optional`, `std::expected`, and `std::any` provided out of the box. For example:
 
@@ -169,7 +169,7 @@ Here are some `as` casts with their Cpp1 equivalents. In this table, uppercase n
 > Note: `as` unifies a variety of differently-named Cpp1 language and library casts and conversions under one syntax, and supports only the type-safe ones.
 
 
-## `inspect` — pattern matching
+## <a id="inspect"></a> `inspect` — pattern matching
 
 An `inspect expr -> Type` expression allows pattern matching using `is`.
 
@@ -210,7 +210,7 @@ test(42);
 For more examples, see also the examples in the previous two sections on `is` and `as`, many of which use `inspect`.
 
 
-## `$` — captures, including interpolations
+## <a id="captures"></a> `$` — captures, including interpolations
 
 Suffix `$` is pronounced **"paste the value"** and captures the value of an expression at the point when the expression where the capture is written is evaluated. Depending the complexity of the capture expression `expr$` and where it is used, parentheses `(expr)$` may be required for precedence or to show the boundaries of the expression.
 
@@ -219,7 +219,7 @@ Suffix `$` is pronounced **"paste the value"** and captures the value of an expr
 Any capture is evaluated at the point where it is written, in the function expression, contract postcondition, or string literal. The stored captured value can then be used later when the context it is in is evaluated, such as when the function expression body it's in is actually called later (one or more times), when the postcondition it's in is evaluated later when the function returns, or when the string literal it's in is read later.
 
 
-### Capture in function expressions (aka lambdas)
+### <a id="function-captures"></a> Capture in function expressions (aka lambdas)
 
 Any capture in a function expression body is evaluated at the point where the function expression is written, at the declaration of the function expression. The function expression itself is then evaluated each time the function is invoked, and can reference the captured value.
 
@@ -240,7 +240,7 @@ main: () = {
 The design and syntax are selected so that capture is spelled the same way in all contexts. For details, see [Design note: Capture](https://github.com/hsutter/cppfront/wiki/Design-note%3A-Capture).
 
 
-### Capture in contract postconditions
+### <a id="postcondition-captures"></a> Capture in contract postconditions
 
 Any capture in a postcondition is evaluated at the point where the postcondition is written, at the beginning (entry) of the function. The postcondition itself is then evaluated when the function returns, and can reference the captured value.
 
@@ -256,7 +256,7 @@ push_back: (coll, value)
 ```
 
 
-### Capture in string interpolation
+### <a id="interpolation"></a> Capture in string interpolation
 
 A string literal can capture the value of an expression `expr` by writing `(expr)$` inside the string literal. The `(` `)` are required, and cannot be nested. A string literal has type `std::string` if it performs any captures, otherwise it is a normal C/C++ string literal (array of characters).
 

Diff for: docs/cpp2/functions.md

@@ -6,7 +6,7 @@
 TODO
 
 
-## Parameters
+## <a id="parameters"></a> Parameters
 
 There are six ways to pass parameters that cover all use cases:
 
@@ -23,12 +23,12 @@ There are six ways to pass parameters that cover all use cases:
 > Note: All parameters and other objects in Cpp2 are `#!cpp const` by default, except for local variables. For details, see [Design note: `#!cpp const` objects by default](https://github.com/hsutter/cppfront/wiki/Design-note%3A-const-objects-by-default).
 
 
-## Return values
+## <a id="return-values"></a> Return values
 
 TODO
 
 
-### Function outputs
+### <a id="nodiscard-outputs"></a> Function outputs are not implicitly discardable
 
 A function's outputs are its return values, and the "out" state of any `out` and `inout` parameters.
 
@@ -74,13 +74,13 @@ main: ()
 > - A function call written in Cpp2 `x.f()` member call syntax always treats a non-`#!cpp void` return type as not discardable, even if the function was written in Cpp1 syntax that did not write `[[nodiscard]]`.
 
 
-## Control flow
+## <a id="control flow"></a> Control flow
 
-## `#!cpp if`, `#!cpp else` — Branches
+## <a id="branches"></a> `#!cpp if`, `#!cpp else` — Branches
 
 TODO
 
-## `#!cpp for`, `#!cpp while`, `#!cpp do` — Loops
+## <a id="loops"></a> `#!cpp for`, `#!cpp while`, `#!cpp do` — Loops
 
 TODO
 
@@ -104,15 +104,15 @@ outer: while i<M next i++ {      // loop named "outer"
 }
 ```
 
-## Unnamed function expressions (aka lambdas)
+## <a id="function-expressions"></a> Unnamed function expressions (aka lambdas)
 
 TODO
 
-## Move/forward from last use
+## <a id="definite-last-use"></a> Move/forward from definite last use
 
 TODO
 
-## Generality: Unifying functions and local scopes
+## <a id="function-scope-unification"></a> Generality: Unifying functions and local scopes
 
 TODO
 

Diff for: docs/cpp2/metafunctions.md

@@ -11,7 +11,7 @@ A metafunction is a compile-time function that can participate in interpreting t
 
 The most important thing about metafunctions is that they are not hardwired language features — they are compile-time library code that uses the reflection and code generation API, that lets the author of an ordinary type easily opt into a named set of defaults, requirements, and generated contents. This approach is essential to making the language simpler, because it lets us avoid hardwiring special "extra" types into the language and compiler.
 
-## Applying metafunctions
+## <a id="applying-metafunctions"></a> Applying metafunctions
 
 Metafunctions provide an easy way for a type author to opt into a group of defaults, constraints, and generated functions: Just write `@name` afer the `:` of a declaration, where `name` is the name of the metafunction. This lets the type author declare (and the human reader see) the intent up front: "This isn't just any `type`, this is a `@value type`" which automatically gives the type default/copy/move construction and assignment, `<=>` with `std::strong_ordering` comparisons, and guarantees that it has a public destructor and no protected or virtual functions:
 
@@ -26,12 +26,12 @@ point2d: @value type = {
 }
 ```
 
-## Generating source code at compile time
+## <a id="generating-source"></a>Generating source code at compile time
 
 TODO
 
 
-## Built-in metafunctions
+## <a id="built-in-metafunctions"></a>Built-in metafunctions
 
 The following metafunctions are provided in the box with cppfront.
 
@@ -45,7 +45,7 @@ TODO
 TODO
 
 
-### ordered, weakly_ordered, partially_ordered
+### <a id="ordered"></a>ordered, weakly_ordered, partially_ordered
 
 TODO
 
@@ -55,7 +55,7 @@ TODO
 TODO
 
 
-### basic_value, value, weakly_ordered_value, partially_ordered_value
+### <a id="value"></a>basic_value, value, weakly_ordered_value, partially_ordered_value
 
 TODO
 
@@ -65,7 +65,7 @@ TODO
 TODO
 
 
-### `enum`, `flag_enum`
+### `enum`
 
 Cpp2 has no `enum` feature hardwired into the language. Instead you apply the `@enum` metafunction when writing an ordinary `type`:
 
@@ -111,7 +111,9 @@ janus: @enum type = {
 }
 ```
 
-There's also a `flag_enum` variation with power-of-two semantics and an unsigned underlying type:
+### `flag_enum`
+
+`flag_enum` is a variation on `enum` that has power-of-two default enumerator values, a default unsigned underlying type, and supports bitwise operators:
 
 ``` cpp title="Using the @flag_enum metafunction when writing a type" hl_lines="11"
 // file_attributes is declaratively a safe flag enum type:
@@ -207,12 +209,12 @@ TODO
 TODO
 
 
-## Writing your own metafunctions
+## <a id="writing-metafunctions"></a> Writing your own metafunctions
 
 TODO
 
 
-## Reflection API reference
+## <a id="reflection-api"></a> Reflection API reference
 
 TODO
 

Diff for: docs/cpp2/objects.md

@@ -6,7 +6,7 @@ Its declaration is written using the same **name `:` kind `=` value** [declarati
 
 - **name** starts with a letter and is followed by other letters, digits, or `_`. Examples: `count`, `skat_game`, `Point2D` are valid names.
 
-- **kind** is the object's type. In most places, except type scopes, you can write the `_` wildcard as the type (or omit the type entirely) to ask for the type to be deduced. When the type is a template, the templated arguments can be inferred from the constructor (via [CTAD](../welcome/hello-world.md#CTAD)).
+- **kind** is the object's type. In most places, except type scopes, you can write the `_` wildcard as the type (or omit the type entirely) to ask for the type to be deduced. When the type is a template, the templated arguments can be inferred from the constructor (via [CTAD](../welcome/hello-world.md#ctad)).
 
 - **value** is the object's initial value. To use the default-constructed value, write `()`.
 
@@ -26,7 +26,7 @@ count := -1;        // same, deducing the object's type by just omitting it
 ```
 
 
-## <a id="Init"></a> Guaranteed initialization
+## <a id="init"></a> Guaranteed initialization
 
 Every object must be initialized using `=` before it is used.
 
@@ -95,7 +95,7 @@ load_from_disk: (out buffer) = {
 In the above example, note the simple rule for branches: The local variable must be initialized on both the `#!cpp if` and `#!cpp else` branches, or neither branch.
 
 
-## Heap objects
+## <a id="heap"></a>Heap objects
 
 Objects can also be allocated on the heap using `#!cpp arena.new <T> (/*initializer, arguments*/)` where `arena` is any object that acts as a memory arena and provides a `#!cpp .new` function template. Two memory arena objects are provided in namespace `cpp2`: