rename things

src/SUMMARY.md

@@ -1,18 +1,13 @@
 # Summary
 
-- [Rust's goals](./goals.md)
-- [How Rust ought to feel](./how_rust_feels.md)
-    - [⚙️ Reliable](./how_rust_feels/reliable.md)
-    - [🐎 Performant](./how_rust_feels/performant.md)
-    - [🧩 Productive](./how_rust_feels/productive.md)
-    - [🔧 Transparent](./how_rust_feels/transparent.md)
-    - [🥰 Supportive](./how_rust_feels/supportive.md)
-    - [🤸 Versatile](./how_rust_feels/versatile.md)
-- [Mechanisms](./mechanisms.md)
-    - [Type safety](./mechanisms/type_safety.md)
-    - [Zero-cost abstractions](./mechanisms/type_safety.md)
-    - [Editions](./mechanisms/editions.md)
-    - [Expose all system capabilities](./mechanisms/expose_capabilities.md)
+- [What is Rust?](./what_is_rust.md)
+- [Rust empowers by being...](./how_rust_empowers.md)
+    - [⚙️ Reliable](./how_rust_empowers/reliable.md)
+    - [🐎 Performant](./how_rust_empowers/performant.md)
+    - [🧩 Productive](./how_rust_empowers/productive.md)
+    - [🥰 Supportive](./how_rust_empowers/supportive.md)
+    - [🔧 Transparent](./how_rust_empowers/transparent.md)
+    - [🤸 Versatile](./how_rust_empowers/versatile.md)
 - [How to Rustacean](./how_to_rustacean.md)
     - [💖 Be kind and considerate](./how_to_rustacean/be_kind.md)
     - [✨ Bring joy to the user](./how_to_rustacean/bring_joy.md)
@@ -22,5 +17,8 @@
     - [✅ Follow through](./how_to_rustacean/follow_through.md)
     - [🤝 Pay it forward](./how_to_rustacean/pay_it_forward.md)
     - [🎁 Trust and delegate](./how_to_rustacean/trust_and_delegate.md)
-- [📜 Case studies](./case_studies.md)
+- [📜 Mechanisms](./case_studies.md)
+    - [Type safety](./case_studies/type_safety.md)
+    - [Portability](./case_studies/disjoint_closures.md)
+    - [](./case_studies/disjoint_closures.md)
 - [❓ FAQ](./FAQ.md)

src/case_studies/disjoint_closures.md

@@ -0,0 +1 @@
+# Disjoint closure capture

src/case_studies/type_safety.md

@@ -0,0 +1 @@
+# Type safety

src/how_rust_feels.md → src/how_rust_empowers.md

@@ -1,6 +1,8 @@
 # How Rust ought to feel
 
-This section identifies the way that Rust ought to feel, when everything is going right. These are the goals by which we evaluate new features.
+Rust's [overall goal](./goals.md) is to "empower everyone to build reliable and efficient software". But how do we do that? This section identifies various specific goals for what it feels like when Rust is empowering.
+
+**Note that these goals are often in tension.** We always try to be be helpful or neutral on all of these goals; in some cases, though, we may be forced to decide between slightly penalizing one goal or another. In that case, we tend to support those goals that come earlier in the list over those that come later.
 
 ## [⚙️ Reliable](./how_rust_feels/reliable.md): "if it compiles, it works"
 
@@ -14,14 +16,14 @@ This section identifies the way that Rust ought to feel, when everything is goin
 
 > Rust and its ecosystem offer a wide array of powerful building blocks that can be combined and recombined. The result is that standing up quality code can be done in record time.
 
-## [🔧 Transparent](./how_rust_feels/transparent.md): "able to predict low-level details and control them"
-
-> The translation from Rust to underlying machine code is straightforward and predictable. If needed, you have options to control the low-level details of how your application works.
-
 ## [🥰 Supportive](./how_rust_feels/supportive.md): "build the system you want to build, whoever you are"
 
 > We strive to make our tools polished and friendly, and we look for every opportunity to guide people towards success. Part of that is building a community that eagerly shares its knowledge in a welcoming and inclusive way.
 
+## [🔧 Transparent](./how_rust_feels/transparent.md): "able to predict low-level details and control them"
+
+> The translation from Rust to underlying machine code is straightforward and predictable. If needed, you have options to control the low-level details of how your application works.
+
 ## [🤸 Versatile](./how_rust_feels/versatile.md): "whatever it is I want to do, I can use Rust to do it"
 
 > Rust scales well both up and down: it is well-suited to building everything from simple scripts to web servers to WebAssembly programs to kernel extensions and embedded systems. It is usable on both common and esoteric platforms.

src/how_rust_empowers/performant.md

@@ -0,0 +1,13 @@
+# 🏇 Performant: "ran well right out of the box"
+
+> > In Rust, the fastest code is often the most high-level: convenient features like closures, iterators, or async-await map down to code that is at once efficient and which uses minimal memory.
+
+## Examples
+
+### Iterators
+
+Rust iterators are a good example of something which meets our goal of being *performant*. Code that uses iterators not only feels higher-level, it often compiles down to loops which are more efficient than if you wrote the loops with explicit iterators. This is because iterators are able to skip bounds checks on vectors.
+
+### Async-await
+
+The goal with async-await syntax is to make a convenient, accessible way to write code which compiles down to the same sort of state machines that C programmers have been writing by hand to create event-driven architectures.

src/how_rust_empowers/productive.md

@@ -0,0 +1,9 @@
+# 🧩 Productive
+
+> Rust and its ecosystem offer a wide array of powerful building blocks that can be combined and recombined. The result is that standing up quality code can be done in record time.
+
+## Examples
+
+### Stability without stagnation and editions
+
+One of Rust's [core deliverables](https://blog.rust-lang.org/2014/10/30/Stability.html) 

src/mechanisms/expose_capabilities.md

@@ -0,0 +1 @@
+# Expose all system capabilities

src/goals.md → src/what_is_rust.md

@@ -2,12 +2,12 @@
 
 ## What is Rust?
 
-* A language empowering everyone to build reliable and efficient software that is meant to last.
-* An open-source community focused on creating, designing, and maintaining that language and its ecosystem.
+* A language **empowering everyone to build reliable and efficient software**.
+* An **open-source community** focused on creating, designing, and maintaining that language and its ecosystem.
 
 ## What are the Rustacean Principles?
 
-The **Rustacean principles** are a set of principles which guide us in building Rust. They begin with a description of [how Rust ought to feel](./how_rust_feels.md) when you are using it. These goals guide us in designing features and help us decide how to 
+The **Rustacean principles** are a set of principles which guide us in building Rust. They begin with a description of [how Rust empowers its users](./how_rust_empowers.md). These goals guide us in designing features and help us decide how to 
 
 * [How Rust ought to feel](./how_rust_feels.md) covers the underlying design principles of Rust.
 * [How to Rustacean](./how_to_rustacean.md) describes the way that Rust team members are expected to act. You can think of it like a companion to the [Code of Conduct][CoC]: whereas the [CoC] describes the bare minimum expected of any Rust participant, the [How to Rustacean] section describes what is takes to become a member of a Rust team.