Add interpolation formatting, and other minor cleanup

Author: hsutter

docs/cpp2/expressions.md

@@ -212,7 +212,7 @@ For more examples, see also the examples in the previous two sections on `is` an
 
 ## `$` — captures, including interpolations
 
-Suffix `$` is pronounced **"paste the value of"** 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.
+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.
 
 `x$` always captures `x` by value. To capture by reference, take the address and capture a pointer using `x&$`. If the value is immediately used, dereference again; for example `:(val) total&$* += val` adds to the `total` local variable itself, not a copy.
 
@@ -225,14 +225,14 @@ Any capture in a function expression body is evaluated at the point where the fu
 
 For example:
 
-``` cpp title="Capture in an unnamed function expression (aka lambda)" hl_lines="6 7"
+``` cpp title="Capture in an unnamed function expression (aka lambda)" hl_lines="6"
 main: () = {
     s := "-sh\n";
     vec: std::vector = (1, 2, 3, 5, 8, 13 );
 
     vec.std::ranges::for_each(
         :(i) = { std::cout << i << s$; }
-        //  Function capture: Paste local variable value
+           //  Paste the value of `s`
     );
 }
 ```
@@ -246,10 +246,10 @@ Any capture in a postcondition is evaluated at the point where the postcondition
 
 For example:
 
-``` cpp title="Capture in contract postconditions" hl_lines="2 3"
+``` cpp title="Capture in contract postconditions" hl_lines="2"
 push_back: (coll, value)
     [[post: coll.ssize() == coll.ssize()$ + 1]]
-        //  Postcondition capture: Paste  "old" size
+    //  Paste the value of `coll.ssize()`
 = {
     // ...
 }
@@ -258,22 +258,23 @@ push_back: (coll, value)
 
 ### 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 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).
 
 Any capture in a string literal is evaluated at the point where the string literal is written. The string literal can be used repeatedly later, and includes the captured value.
 
 For example:
 
-``` cpp title="Capture for string interpolation" hl_lines="2 4"
+``` cpp title="Capture for string interpolation" hl_lines="2 5"
 x := 0;
 std::cout << "x is (x)$\n";
+        // Paste the value of `x`
 x = 1;
 std::cout << "now x+2 is (x+2)$\n";
+        // Paste the value of `x+2`
 
 //  prints:
 //      x is 0
 //      now x+2 is 3
 ```
 
-A string literal has type `std::string` if it performs any captures, otherwise it is a normal C/C++ string literal (array of characters).
-
+A string literal capture can include a `:suffix` where the suffix is a [standard C++ format specification](https://en.cppreference.com/w/cpp/utility/format/spec). For example, `#!cpp (x.price(): <10.2f)$` evaluates `x.price()` and converts the result to a string with 10-character width, 2 digits of precision, and left-justified.

docs/welcome/hello-world.md

@@ -1,19 +1,11 @@
 # **Hello, world!**
 
-<table><tr><td>
-``` cpp title="hello.cpp2"
-main: () = {
-    std::cout << "Hello, world!\n";
-}
-```
-</td><td>
 ``` mermaid
-graph TB
-  A[hello.cpp2] ==> B([cppfront]);
+graph LR
+  A[hello.cpp2] ==> B(["` **cppfront** `"]);
   B ==> C[hello.cpp];
-  C ==> D([Your favorite C++ compiler]);
+  C ==> D([Your favorite<br> C++ compiler<p>... and IDE / libraries / build<br>system / in-house tools / ...]);
 ```
-</td></tr></table>
 
 ## A `hello.cpp2` program
 
@@ -30,7 +22,6 @@ main: () = {
     words: std::vector = ( "Alice", "Bob" );
     hello( words[0] );
     hello( words[1] );
-    std::cout << "... and goodnight\n";
 }
 
 hello: (msg: std::string_view) =
@@ -98,7 +89,6 @@ auto main() -> int{
     std::vector words {"Alice", "Bob"};
     hello(CPP2_ASSERT_IN_BOUNDS_LITERAL(words, 0));
     hello(CPP2_ASSERT_IN_BOUNDS_LITERAL(std::move(words), 1));
-    std::cout << "... and goodnight\n";
 }
 
 auto hello(cpp2::in<std::string_view> msg) -> void {
@@ -116,7 +106,7 @@ Here we can see more of how Cpp2 makes it features work.
 - **Line 9: CTAD** just works, because it turns into ordinary C++ code which already supports CTAD.
 - **Lines 10-11: Automatic bounds checking** is added to `#!cpp words[0]` and `#!cpp words[1]` nonintrusively at the call site by default. Because it's nonintrusive, it works seamlessly with all existing container types that are `std::size` and `std::ssize`-aware, when you use them from safe Cpp2 code.
 - **Line 11: Automatic move from last use** ensures the last use of `words` will automatically avoid a copy if it's being passed to something that's optimized for rvalues.
-- **Line 16: String interpolation** performs the string capture of `msg`'s current value via `cpp2::to_string`. That uses `std::to_string` when available, and it also works for additional types (such as `#!cpp bool`, to print `#!cpp false` and `#!cpp true` instead of `0` and `1`, without having to remember to use `std::boolalpha`).
+- **Line 15: String interpolation** performs the string capture of `msg`'s current value via `cpp2::to_string`. That uses `std::to_string` when available, and it also works for additional types (such as `#!cpp bool`, to print `#!cpp false` and `#!cpp true` instead of `0` and `1`, without having to remember to use `std::boolalpha`).
 
 **How: Simplicity through generality + defaults.**
 
@@ -128,7 +118,7 @@ Here we can see more of how Cpp2 makes it features work.
 
 **How: Seamless compatibility and interop.**
 
-- **Lines 9, 12, and 16: Ordinary direct calls** to existing C++ code, so there's never a need for wrapping/marshaling/thunking.
+- **Lines 9-11 and 16: Ordinary direct calls** to existing C++ code, so there's never a need for wrapping/marshaling/thunking.
 
 **How: C++ standard library always available.**