changes to toc and inline

Author: odersky

docs/docs/reference/metaprogramming/inline.md

@@ -58,37 +58,25 @@ If `Config.logging == false`, this will be rewritten (simplified) to
 
 ```scala
 def factorial(n: BigInt): BigInt = {
-  /* parameters of log passed by-name (1) */
-  def msg = s"factorial($n)"
-  def op =
-    if (n == 0) 1
-    else n * factorial(n - 1)
-
-  /* inlined body of log  (2) */
-  op
+  if (n == 0) 1
+  else n * factorial(n - 1)
 }
 ```
 
-and if `true` it will be rewritten in the code below:
+and if `true` it will be rewritten to the code below:
 
 ```scala
 def factorial(n: BigInt): BigInt = {
-  /* parameters of log passed by-name (1) */
-  def msg = s"factorial($n)"
-  def op =
-    if (n == 0) 1
-    else n * factorial(n - 1)
-
-  /* inlined body of log  (2) */
-  println(s"${"  " * indent}start $msg")
-  indent += 1
+  val msgVal = s"factorial($n)"
+  println(s"${"  " * indent}start $msgVal")
+  Logger.inline$indent += 1
   val result = op
-  indent -= 1
-  println(s"${"  " * indent}$msg = $result")
+  Logger.inline$indent -= 1
+  println(s"${"  " * indent}$msgVal = $result")
   result
 }
 ```
-
+TODO: adapt to real code.
 Note (1) that the arguments corresponding to the parameters `msg` and `op` of
 the inline method `log` are defined before the inlined body (which is in this
 case simply `op` (2)). By-name parameters of the inline method correspond to

docs/docs/reference/metaprogramming/toc.md

@@ -6,45 +6,40 @@ title: "Overview"
 The following pages introduce the redesign of metaprogramming in Scala. They
 introduce the following fundamental facilities:
 
-1. [Inline](./inline.html) `inline` is a new soft-modifier that guarantees that
+1. [Inline](./inline.html) `inline` is a new modifier that guarantees that
    a definition will be inlined at the point of use. The primary motivation
    behind inline is to reduce the overhead behind function calls and access to
    values. The expansion will be performed by the Scala compiler during the
-   `Typer` compiler phase. However, as opposed to inline in other ecosystems,
+   `Typer` compiler phase. Unlike Scala's existsing
+   As opposed to inline in some other ecosystems,
    inlining is not merely a request to the compiler but for Scala it is a
-   _command_. The reason is that inlining in Scala can driver other compile-time
-   operations too, like inline pattern matching (enabling type-level
+   _command_. The reason is that inlining in Scala can drive other compile-time
+   operations, like inline pattern matching (enabling type-level
    programming), macros (enabling compile-time, generative, metaprogramming) and
-   runtime code generation (multi-stage programming). In this section we
-   describe up to inline pattern matching describing the basic constructs.
+   runtime code generation (multi-stage programming).
 
 2. [Macros](./macros.html) Macros are built on two well-known fundamental
-   operations: quotation and splicing.  Quotation is expressed as `'{...}` for
-   expressions (both forms are equivalent) and as `'[...]` for types. Splicing
-   is expressed as `${ ... }`. Whereas inlining is driven completely by the
-   language level features of scala (pattern matching, inline vals and
-   definitions), macros enable is synthesize/compute code at will treating code
-   values as first class citizens and splicing them together independently.
-   Here, we move towards _domain-specific_ metaprogramming.
-
-3. [Staging](./staging.html) Macros can be seen as distinct phase while
-   programming. You write your regular code that will be compiled according to
-   the semantics of the language and the macro code that is going to be
-   "compiled" or "generated" according the intented purpose of the programmer.
-   Staging (or Multi-Stage Programming) can be seen as taking one step further
-   this exact concept and can make code generation depent not only on static
-   data but also on data available at _runtime_. This splits the evaluation of
-   the program in many phases or ... stages, thus the "Multi-Stage" in the
-   programming paradigm we say it supports.
-
-4. [TASTy Reflection](./tasty-reflect.html) With TASTy reflection we can
-   `unseal` fragments of code and analyze them with reflection over the TASTy
-   format of the code.
-
-5. [TASTy Inspection](./tasty-inspect.html) Up until now we described how we can
-   expand, calculate at compile-time, or generate programs. The Scala compiler
-   offers quarantees at the level of types that the generated programs cannot go
-   wrong. With TASTy inspection we can load compiled files and analyze their
-   typed AST structure according to the TASTy format.
-
+   operations: quotation and splicing.  Quotation converts program code to
+   data, specifically, a (tree-like) representation of this code. It is
+   expressed as `'{...}` for expressions and as `'[...]` for types. Splicing,
+   expressed as `${ ... }`, goes the other way: it converts a program's representation
+   to program code. Together with `inline`, these two abstractions allow
+   to construct program code programmatically.
+
+3. [Staging](./staging.html) Where macros construct code at _compile-time_,
+   staging lets programs construct new code at _runtime_. That way,
+   code generation can depend not only on static data but also on data available at runtime. This splits the evaluation of the program in two or more phases or ...
+   stages. Consequently, this method generative programming is called "Multi-Stage Programming". Staging is built on the same foundations as macros. It uses
+   quotes and splices, but leaves out `inline`.
+
+4. [TASTy Reflection](./tasty-reflect.html) Quotations are a "black-box"
+   representation of code. They can be parameterized and composed using
+   splices but their structure cannot be analyzed from the outside. Tasty
+   reflection gives a way to analyze code structure by partly revealing the representation type of a piece of code in a standard API. The representation
+   type is a form of typed abstract syntax tree, which gives rise to the "TASTy`
+   moniker.
+
+5. [TASTy Inspection](./tasty-inspect.html) Typed abstract syntax trees are serialized
+   in a custom compressed binary format in `.tasty` files. TASTy inspection allows
+   to load these files and analyze their content's tree structure.