Address some review comments. Fill out rationale.

Author: zygoloid

docs/project/principles/namespace_cleanliness.md

@@ -34,8 +34,8 @@ for entities. Different languages make different choices in this space:
 
 -   Many languages have a set of keywords that are not usable as identifiers,
     with no workaround. If this set collides with a name needed by user code,
-    the user is left to solve this problem, often by rewriting the
-    identifier in some way (`klass` or `class_`), which sometimes conflicts with the general
+    the user is left to solve this problem, often by rewriting the identifier in
+    some way (`klass` or `class_`), which sometimes conflicts with the general
     naming convention used by the code. And conversely, suboptimal choices are
     made for new language keywords to avoid causing problems for existing code.
 -   C and C++ reserve a family of identifiers, such as those beginning with an
@@ -44,7 +44,12 @@ for entities. Different languages make different choices in this space:
     library vendors and compiler authors, as well as between implementation
     extensions and language extensions.
     -   MSVC provides a `__identifier(keyword)` extension that allows using a
-        keyword as an identifier.
+        keyword as an identifier. This extension is also implemented by Clang in
+        `-fms-extensions` mode.
+    -   GCC provides an `__asm__(symbol)` extension that allows a specific
+        symbol to be assigned to an object or function, which provides ABI
+        compatibility but not source compatibility with code that uses a keyword
+        as a symbol name. This extension is also implemented by Clang.
 -   Python reserves some identifiers but still allows them to be freely
     overwritten (such as `bool`) and reserves some identifiers but rejects
     assignment to them (such as `True`).
@@ -61,10 +66,11 @@ for entities. Different languages make different choices in this space:
     extending this to allow arbitrary non-word-shaped character sequences
     between the `` ` ``s.
 
-Carbon provides raw identifier syntax, for example `r#for`, to allow using
-keywords as identifiers. Carbon also has strict shadowing rules that mean that
-predeclared identifiers that are _not_ keywords are difficult or impossible to
-redeclare and use in inner scopes.
+Carbon provides
+[raw identifier syntax](/docs/design/lexical_conventions/words.md#raw-identifiers),
+for example `r#for`, to allow using keywords as identifiers. Carbon also intends
+to have strict shadowing rules that may make predeclared identifiers that are
+_not_ keywords difficult or impossible to redeclare and use in inner scopes.
 
 ## Principle
 
@@ -77,7 +83,8 @@ Conversely, when adding language keywords, we will not select an inferior
 keyword merely to avoid the risk of breaking existing programs. We will still
 take into account how often it is desirable to use the word as an identifier,
 including in domain-specific contexts, because that is a factor in whether it
-would make a good keyword.
+would make a good keyword, and will manage the rollout of new keywords to make
+it straightforward to migrate existing uses to `r#` or a different name.
 
 ## Applications of this principle
 

proposals/p4864.md

@@ -68,22 +68,44 @@ clarification:
     -   As a keyword naming the `Core` package, much like the `package` keyword.
 
     The identifier `r#Core` can be used freely and does not conflict with the
-    keyword. This includes use of `r#Core` as the name of a package.
+    keyword. This includes use of `r#Core` as the name of a package. Language
+    constructs that are defined in terms of entities in the `Core` package refer
+    specifically to the package named with the _keyword_ `Core`, not to any
+    other entity named `Core`.
 
 -   The `self` keyword is now included in the list of keywords. It is already
     treated as a keyword by the toolchain.
 
 ## Rationale
 
--   [Community and culture](/docs/project/goals.md#community-and-culture)
 -   [Language tools and ecosystem](/docs/project/goals.md#language-tools-and-ecosystem)
--   [Performance-critical software](/docs/project/goals.md#performance-critical-software)
+    -   Code generation tools can have a uniform handling for all words with
+        special meaning, with no need to alter the spelling of names from other
+        languages.
+    -   Language tools can determine the meaning of `Core.<name>` without
+        needing to do any name lookup or sophisticated analysis.
 -   [Software and language evolution](/docs/project/goals.md#software-and-language-evolution)
+    -   Migration between versions of Carbon with a changed set of reserved
+        words can be done uniformly.
+    -   Adding names to the prelude remains a non-breaking change. Adding new
+        predeclared names requires adding a keyword, with the same cost and
+        value tradeoffs regardless of whether the keyword names a library
+        declaration or introduces new language syntax.
 -   [Code that is easy to read, understand, and write](/docs/project/goals.md#code-that-is-easy-to-read-understand-and-write)
--   [Practical safety and testing mechanisms](/docs/project/goals.md#practical-safety-and-testing-mechanisms)
--   [Fast and scalable development](/docs/project/goals.md#fast-and-scalable-development)
--   [Modern OS platforms, hardware architectures, and environments](/docs/project/goals.md#modern-os-platforms-hardware-architectures-and-environments)
+    -   Syntax highlighting tools can easily distinguish between words with
+        special meaning and words with program-defined meaning.
+    -   The meaning of core language constructs can be defined as a rewrite in
+        terms of `Core.<name>` without concern that `Core` may have some
+        different local interpretation.
 -   [Interoperability with and migration from existing C++ code](/docs/project/goals.md#interoperability-with-and-migration-from-existing-c-code)
+    -   All C++ identifiers are nameable from Carbon code without conflicts.
+        Virtual functions introduced in Carbon can be overridden in Carbon
+        regardless of their name. C++ code can be migrated to Carbon even if its
+        name in C++ has special meaning in Carbon.
+-   [Principle: Prefer providing only one way to do a given thing](/docs/project/principles/one_way.md)
+    -   This proposal specifies that there is only one way to give words special
+        meaning in Carbon, and one way to resolve issues if that special meaning
+        conflicts with another desired meaning.
 
 ## Future work