Automated fixes using check-google-doc-style (#193)

With one manual ignore in the markdown style proposal, because it's explicitly listing disallowed terms.

docs/design/code_and_name_organization/README.md

@@ -49,7 +49,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
         -   [Referring to the package as `package`](#referring-to-the-package-as-package)
         -   [Remove the `library` keyword from `package` and `import`](#remove-the-library-keyword-from-package-and-import)
         -   [Rename package concept](#rename-package-concept)
-        -   [No association between the filesystem path and library/namespace](#no-association-between-the-filesystem-path-and-librarynamespace)
+        -   [No association between the file system path and library/namespace](#no-association-between-the-file-system-path-and-librarynamespace)
     -   [Libraries](#libraries-1)
         -   [Allow exporting namespaces](#allow-exporting-namespaces)
         -   [Allow importing implementation files from within the same library](#allow-importing-implementation-files-from-within-the-same-library)
@@ -765,7 +765,7 @@ These choices are made to assist human readability and tooling:
     tooling to determine what to expect.
 -   Repeating the type in the filename makes it possible to check the type
     without reading file content.
--   Repeating the type in the file content makes non-filesystem-based builds
+-   Repeating the type in the file content makes non-file-system-based builds
     possible.
 
 ## Open questions
@@ -1020,7 +1020,7 @@ Disadvantages:
     -   [Swift](https://developer.apple.com/documentation/swift_packages), as a
         distributable unit.
 
-#### No association between the filesystem path and library/namespace
+#### No association between the file system path and library/namespace
 
 Several languages create a strict association between the method for pulling in
 an API and the path to the file that provides it. For example:
@@ -1028,10 +1028,10 @@ an API and the path to the file that provides it. For example:
 -   In C++, `#include` refers to specific files without any abstraction.
     -   For example, `#include "PATH/TO/FILE.h"` means there's a file
         `PATH/TO/FILE.h`.
--   In Java, `package` and `import` both reflect filesystem structure.
+-   In Java, `package` and `import` both reflect file system structure.
     -   For example, `import PATH.TO.FILE;` means there's a file
         `PATH/TO/FILE.java`.
--   In Python, `import` requires matching filesystem structure.
+-   In Python, `import` requires matching file system structure.
     -   For example, `import PATH.TO.FILE` means there's a file
         `PATH/TO/FILE.py`.
 -   In TypeScript, `import` refers to specific files.
@@ -1053,7 +1053,7 @@ Advantages:
 -   The strict association makes it harder to move names between files without
     updating callers.
 -   If there were a strict association of paths, it would also need to handle
-    filesystem-dependent casing behaviors.
+    file system dependent casing behaviors.
     -   For example, on Windows, `project.carbon` and `Project.carbon` are
         conflicting filenames. This is exacerbated by paths, wherein a file
         `config` and a directory `Config/` would conflict, even though this
@@ -1061,15 +1061,15 @@ Advantages:
 
 Disadvantages:
 
--   A strict association between filesystem path and import path makes it easier
-    to find source files. This is used by some languages for compilation.
+-   A strict association between file system path and import path makes it
+    easier to find source files. This is used by some languages for compilation.
 -   Allows getting rid of the `package` keyword by inferring related information
-    from the filesystem path.
+    from the file system path.
 
-We are choosing to have some association between the filesystem path and library
-for API files to make it easier to find a library's files. We are not getting
-rid of the `package` keyword because we don't want to become dependent on
-filesystem structures, particularly as it would increase the complexity of
+We are choosing to have some association between the file system path and
+library for API files to make it easier to find a library's files. We are not
+getting rid of the `package` keyword because we don't want to become dependent
+on file system structures, particularly as it would increase the complexity of
 distributed builds.
 
 ### Libraries
@@ -1190,14 +1190,14 @@ Advantages:
 
 -   Clearer distinction between the package and library, increasing readability.
 -   We have chosen not to
-    [enforce filesystem paths](#strict-association-between-the-filesystem-path-and-librarynamespace)
+    [enforce file system paths](#strict-association-between-the-file-system-path-and-librarynamespace)
     in order to ease refactoring, and encouraging a mental model where they may
     match could confuse users.
 
 Disadvantages:
 
 -   Uses multiple separators, so people need to type different characters.
--   There is a preference for thinking of libraries like filesystem paths, even
+-   There is a preference for thinking of libraries like file system paths, even
     if they don't actually correspond.
 
 People like `/`, so we're going with `/`.

docs/design/name_lookup.md

@@ -67,7 +67,7 @@ reference.
 #### Alternatives
 
 This implies that other names within your own package but not declared within
-the file must be found via the package name. It isn't clear if this is the
+the file must be found by way of the package name. It isn't clear if this is the
 desirable end state. We need to consider alternatives where names from the same
 library or any library in the same package are made immediately visible within
 the package scope for unqualified name lookup.

docs/design/primitive_types.md

@@ -87,7 +87,7 @@ the need to import things gratuitously.
 
 ### String view vs owning string
 
-The right model of a string view vs. an owning string is still very much
+The right model of a string view versus an owning string is still very much
 unsettled.
 
 ### Syntax for wrapping operations

docs/design/structs.md

@@ -77,7 +77,7 @@ constraints.
 
 The type itself is a compile-time constant value. All name access is done with
 the `.` notation. Constant members (including member types and member functions
-which do not need an implicit object parameter) can be accessed via that
+which do not need an implicit object parameter) can be accessed by way of that
 constant: `AdvancedWidget.NestedType`. Other members and member functions
 needing an object parameter (or "methods") must be accessed from an object of
 the type.
@@ -99,8 +99,8 @@ special `Self` type.
 
 It may be interesting to consider separating the `self` syntax from the rest of
 the parameter pattern as it doesn't seem necessary to inject all of the special
-rules (covariance vs. contravariance, special pointer handling) for `self` into
-the general pattern matching system.
+rules (covariance versus contravariance, special pointer handling) for `self`
+into the general pattern matching system.
 
 ### Default access control level
 

docs/design/syntactic_conventions.md

@@ -65,11 +65,11 @@ like something that people will get used to with time, it may be worthwhile to
 do some user research to understand the likely reaction distribution, strength
 of reaction, and any quantifiable impact these options have on measured
 readability. We have only found one _very_ weak source of research that focused
-on the _order_ question (rather than type inference vs. explicit types or other
-questions in this space). That was a very limited PhD student's study of Java
-programmers that seemed to indicate improved latency for recalling the type of a
-given variable name with types on the left (as in C++). However, those results
-are _far_ from conclusive.
+on the _order_ question (rather than type inference versus explicit types or
+other questions in this space). That was a very limited PhD student's study of
+Java programmers that seemed to indicate improved latency for recalling the type
+of a given variable name with types on the left (as in C++). However, those
+results are _far_ from conclusive.
 
 **TODO**: Get a useful link to this PhD research (a few of us got a copy from
 the professor directly).

docs/project/commenting_guidelines.md

@@ -24,8 +24,8 @@ always try to keep feedback, even when critical, constructive and supportive.
     keep the discussion focused in one place: the GitHub pull request.
 
     -   If your comment represents a significant change to the proposal, include
-        a list of pros and cons. Even if the author disagrees with the change,
-        they can use those to document the alternative.
+        a list of advantages and disadvantages. Even if the author disagrees
+        with the change, they can use those to document the alternative.
     -   Feel free to extract long side discussions to a Discourse Forum topic,
         but make sure any important conclusions or outcomes are reflected in
         either the GitHub comments or the change itself.

docs/project/consensus_decision_making.md

@@ -91,9 +91,10 @@ weekly meeting slot, which observers may attend. Members are expected to do
 their best to keep the slot available. Meetings will be held using Google
 Hangouts Meet.
 
-Each time a team needs to make a decision, e.g., about a change to Carbon, it is
-expected that we'll try to make a decision without using a live meeting. We will
-only hold meetings when decisions cannot be resolved before the meeting.
+Each time a team needs to make a decision, for example, about a change to
+Carbon, it is expected that we'll try to make a decision without using a live
+meeting. We will only hold meetings when decisions cannot be resolved before the
+meeting.
 
 ### Agenda
 

docs/project/contribution_tools.md

@@ -74,7 +74,7 @@ To set up pre-commit, see the
 ```bash
 pip install pre-commit
 
-# From within each carbon-language git repo:
+# From within each carbon-language git repository:
 pre-commit install
 ```
 
@@ -111,7 +111,7 @@ PR and proposal file for a new proposal. It's documented in
 is a helper for scanning comments in GitHub. It's particularly intended to help
 find threads which need to be resolved.
 
-Flags can be seen with `-h`. A couple key flags to be aware of are:
+Options can be seen with `-h`. A couple key options to be aware of are:
 
 -   `--long`: Prints long output, with the full comment.
 -   `--comments-after LOGIN`: Only print threads where the final comment is not
@@ -143,7 +143,7 @@ brew install github/gh/gh
 #### GitHub Desktop
 
 [GitHub Desktop](https://desktop.github.com/) provides a UI for managing git
-repos. See the page for installation instructions.
+repositories. See the page for installation instructions.
 
 ### Vim
 

docs/project/evolution.md

@@ -253,10 +253,10 @@ community's engagement in it. Beyond the above structure, try to use
 or [BLUF](<https://en.wikipedia.org/wiki/BLUF_(communication)>) writing style to
 help readers rapidly skim the material.
 
-The proposal's pull request may include changes in the same repo. Please be
-thoughtful about how much effort you invest this way: it can help illustrate the
-intent of a proposal and avoid duplicating text in the proposal, but proposals
-may also need to be rewritten substantially or be deferred/declined.
+The proposal's pull request may include changes in the same repository. Please
+be thoughtful about how much effort you invest this way: it can help illustrate
+the intent of a proposal and avoid duplicating text in the proposal, but
+proposals may also need to be rewritten substantially or be deferred/declined.
 
 Where parts of a proposal may have several ways to address them, feel free to
 list options and mark them as "open questions". When describing an open
@@ -338,8 +338,9 @@ believe more changes are needed.
 When significant alternatives are pointed out, include them in the proposal
 regardless of whether they're adopted. The "alternatives" section should be used
 to document rejected alternatives as well as the original approach when an
-alternative is adopted, with pros and cons either way. New "open questions" may
-also be added where the author isn't confident about the best approach.
+alternative is adopted, with advantages and disadvantages either way. New "open
+questions" may also be added where the author isn't confident about the best
+approach.
 
 ##### Actions
 

docs/project/goals.md

@@ -233,7 +233,7 @@ Titus Winters writes in "Non-Atomic Refactoring and Software Sustainability":
 > compatibility over time, dealing with changes to underlying infrastructure and
 > dependencies, and working with legacy code or data. Fundamentally, it is a
 > different task to produce a programming solution to a problem (that solves the
-> current [instance] of the problem) vs. an engineering solution (that solves
+> current [instance] of the problem) versus an engineering solution (that solves
 > current instances, future instances that we can predict, and - through
 > flexibility - allows updates to solve future instances we may not be able to
 > predict).
@@ -364,8 +364,8 @@ cost.
 **Adhere to the principle of least surprise.** Defaults should match typical
 usage patterns. Implicit features should be unsurprising and expected, while
 explicit syntax should inform the reader about any behavior which might
-otherwise be surprising. The core concepts of implicit vs. explicit syntax are
-well articulated in
+otherwise be surprising. The core concepts of implicit versus explicit syntax
+are well articulated in
 [the Rust community](https://blog.rust-lang.org/2017/03/02/lang-ergonomics.html#implicit-vs-explicit),
 although we may come to different conclusions regarding the principles.
 

docs/project/pull_request_workflow.md

@@ -75,8 +75,8 @@ change seems trivial, still go through a pull request -- it'll likely be trivial
 to review. Always wait for someone else to review your pull request rather than
 just merging it, even if you have permission to do so.
 
-Our GitHub repos are configured to require pull requests and review before they
-are merged, so this rule is enforced automatically.
+Our GitHub repositories are configured to require pull requests and review
+before they are merged, so this rule is enforced automatically.
 
 ## Small, incremental changes
 

proposals/README.md

@@ -6,7 +6,7 @@ Exceptions. See /LICENSE for license information.
 SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 -->
 
-This directory contains accepted proposals for the carbon-lang repo. For
+This directory contains accepted proposals for the carbon-lang repository. For
 information about declined/deferred proposals, please view the proposal's
 original pull request.
 
@@ -15,8 +15,8 @@ request:
 
 -   `p####.md` will contain the main proposal text.
 -   `p####-decision.md` documents the decision and rationale.
--   `p####` may be present as an optional subdirectory for related files (e.g.,
-    images).
+-   `p####` may be present as an optional subdirectory for related files (for
+    example, images).
 
 ## Proposal list
 

proposals/p0029.md

@@ -89,13 +89,13 @@ LLVM allows directly pushing/submitting to their "trunk" with post-commit
 review. LLVM enforces linear history for day-to-day development. Merge commits
 are allowed for rare events like contributing a new subproject.
 
-Pros:
+Advantages:
 
 -   Still has linear history.
 -   Incentivizes squashing for continuous integration and bisection.
 -   Very low overhead for fixing trivial mistakes.
 
-Cons:
+Disadvantages:
 
 -   Creates extremely bad incentives around code review.
     -   Lots of patches don't get pre-commit review, even if they would benefit
@@ -113,7 +113,7 @@ Cons:
 Classically, Git and GitHub support merging entire complex graphs of
 development.
 
-Pros:
+Advantages:
 
 -   Mostly supported by pull requests, so still able to use much of that
     functionality.
@@ -125,7 +125,7 @@ Pros:
     -   Most of the time these aren't so complex that they create problems for
         humans.
 
-Cons:
+Disadvantages:
 
 -   History is harder for humans to understand and reason about in complex
     cases.
@@ -146,7 +146,7 @@ branching and merging within a PR, or merging `trunk` into PR is not allowed. In
 this model, the only merge commits are merges of PRs into `trunk`. PRs
 themselves don’t contain merge commits.
 
-Pros:
+Advantages:
 
 -   Mostly supported by GitHub pull requests, so still able to use much of that
     functionality.
@@ -154,8 +154,8 @@ Pros:
     merge commits on the trunk branch. PRs themselves can’t contain merge
     commits.
 
-Cons:
+Disadvantages:
 
 -   Requires a custom presubmit on GitHub that checks linearity of a PR.
--   The cons of the fork and merge strategy regarding the complexity of history
-    remain, but to a smaller degree, since non-linearity is restricted.
+-   The disadvantages of the fork and merge strategy regarding the complexity of
+    history remain, but to a smaller degree, since non-linearity is restricted.

proposals/p0042.md

@@ -64,9 +64,9 @@ included directly, and carbon-language/carbon-toolchain#1 updates the
 ### Post-commit review
 
 Some projects, such as LLVM, use _post-commit_ review for some changes. This has
-both pros and cons.
+both advantages and disadvantages.
 
-Pros:
+Advantages:
 
 -   Enables sustaining velocity in the face of high latency in code review.
     -   Little need to rebase or resolve merge conflicts due to immediately
@@ -75,7 +75,7 @@ Pros:
 -   Optimizes commit velocity amongst a small group of developers with extensive
     experience working together and minimal review comments on others' code.
 
-Cons:
+Disadvantages:
 
 -   Does not meaningfully scale beyond small group of developers with
     pre-existing shared understanding of desired form of code.
@@ -100,7 +100,7 @@ changes for which "no functionality changes" or NFC commits. Common examples are
 reformatting or basic code cleanup. The idea is that these are exceedingly lower
 risk compared changes to functionality.
 
-Pros:
+Advantages:
 
 -   Can avoid waiting for a review on trivial cleanups and refactorings.
     -   May be especially useful as they tend to be merge conflict prone and
@@ -113,7 +113,7 @@ Pros:
         is easier than deciding "given that it changes behavior, is the change
         good?".
 
-Cons:
+Disadvantages:
 
 -   No concrete and objective rubric for whether or not a change is NFC, and
     whether it perhaps is significant enough to still warrant review.

proposals/p0044.md

@@ -20,11 +20,11 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
         -   [Option: Google Docs-centric flow](#option-google-docs-centric-flow)
             -   [Overview](#overview-1)
             -   [Flow summary](#flow-summary)
-            -   [Pros/Cons](#proscons)
+            -   [Advantages/Disadvantages](#advantagesdisadvantages)
         -   [Option: GitHub Markdown-centric flow](#option-github-markdown-centric-flow)
             -   [Overview](#overview-2)
             -   [Flow summary](#flow-summary-1)
-            -   [Pros/Cons](#proscons-1)
+            -   [Advantages/Disadvantages](#advantagesdisadvantages-1)
 -   [Details](#details)
     -   [Carbon language shared drive](#carbon-language-shared-drive)
         -   [Main shared drive](#main-shared-drive)
@@ -33,7 +33,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
     -   [Google Docs proposal ACLs](#google-docs-proposal-acls)
 -   [Markdown-specific questions](#markdown-specific-questions)
     -   [Open question: Where should proposals be stored in GitHub?](#open-question-where-should-proposals-be-stored-in-github)
-        -   [Option: Proposal archive GitHub repo (carbon-proposals)](#option-proposal-archive-github-repo-carbon-proposals)
+        -   [Option: Proposal archive GitHub repository (carbon-proposals)](#option-proposal-archive-github-repository-carbon-proposals)
         -   [Option: Store proposals in the repository they affect](#option-store-proposals-in-the-repository-they-affect)
     -   [Open question: Should we push comments to focus on GitHub?](#open-question-should-we-push-comments-to-focus-on-github)
         -   [Common principles](#common-principles)
@@ -114,7 +114,7 @@ This proposal presents two possible flows: one Google Docs-centric, one
 Markdown-centric. This is an open question.
 
 In either case, it's assumed that we will want a Carbon language shared drive
-for any Google Docs we may create, and a Proposal archive GitHub repo.
+for any Google Docs we may create, and a Proposal archive GitHub repository.
 
 ### Open question: Do we use a Google Docs-centric or GitHub Markdown-centric flow?
 
@@ -146,7 +146,7 @@ For reviewing a proposal:
     -   The review manager trims down all access to comment access.
 -   When a decision is reached, the review manager updates the doc and moves it
     to the Proposal Archive folder in the Carbon language shared drive.
--   A PDF is saved to the carbon-proposals GitHub repo.
+-   A PDF is saved to the carbon-proposals GitHub repository.
 -   The author converts any long-term documentation portions of the doc to
     Markdown.
 
@@ -160,9 +160,9 @@ If the proposal needs to be checked later to figure out why a decision was made:
     Since most people will have comment-only or view-only access to reviewed
     docs, we should treat edit history as not accessible.
 
-##### Pros/Cons
+##### Advantages/Disadvantages
 
-Pros:
+Advantages:
 
 -   Supports collaborative editing.
 -   Commenting in Docs is a slightly better UI, even though the commenting
@@ -178,7 +178,8 @@ Neutral:
     -   For the author, this is a mixed bag:
         -   When a suggestion is for multiple, fragmented edits, it's harder to
             read.
-            -   e.g., "foo ~~bar ~~baaz bang~~wiz ~~bing" -> "foo baaz bangbing"
+            -   for example, "foo ~~bar ~~baaz bang~~wiz ~~bing" -> "foo baaz
+                bangbing"
         -   It's easier to accept changes.
         -   It's harder to comment on changes, as the change is still visible
             and hiding the original state of the doc.
@@ -192,7 +193,7 @@ Neutral:
         original state of the doc that's been suggested on, and it's not clear
         how the author will respond.
 
-Cons:
+Disadvantages:
 
 -   Documents will go through at least three different file formats (Docs, PDF,
     Markdown).
@@ -216,8 +217,8 @@ Cons:
 -   Difficult to archive documents as read-only.
     -   If we set archived documents to be view-only, users won't be able to
         read comments. At that point, the PDF version that we plan to commit to
-        the Proposal archive GitHub repo is sufficient, and we could delete the
-        proposal.
+        the Proposal archive GitHub repository is sufficient, and we could
+        delete the proposal.
     -   If we set archived documents to allow commenting, then users can comment
         on and add suggested edits to archived documents. Only review managers
         could close suggested edits. This could confuse the history of the doc,
@@ -241,10 +242,10 @@ Cons:
         on the part of a doc editor to set up markers in the version history.
 -   Restricted support for extensibility.
     -   Proposals frequently have duplicated/boilerplate text that the authors
-        may need to rewrite in bulk, e.g. when renaming something. Google Docs
-        has built-in regex search. However, regex replace with capture groups
-        isn't directly supported, so users would need to learn and use Google
-        Apps Script to do the replacement.
+        may need to rewrite in bulk, for example when renaming something. Google
+        Docs has built-in regex search. However, regex replace with capture
+        groups isn't directly supported, so users would need to learn and use
+        Google Apps Script to do the replacement.
     -   When URLs need to be replaced, Google Docs has _no_ support. Authors
         must audit every URL.
 -   No low-friction support for formatted code blocks and inline code snippets.
@@ -280,7 +281,7 @@ Cons:
 ##### Overview
 
 -   Draft proposals: Markdown, possibly in Google Docs (but not required)
--   Under review proposals: Markdown with review comments via GitHub
+-   Under review proposals: Markdown with review comments by way of GitHub
 -   Archive proposals: Markdown
 -   Final format: Markdown
 
@@ -292,7 +293,7 @@ For reviewing a proposal:
     -   This could be [a WYSIWYG markdown editor](#markdown-editing), or Google
         docs for collaboration.
 -   Authors create a pull request with the markdown doc, to the carbon-proposals
-    GitHub repo.
+    GitHub repository.
     -   Community comments on the pull request.
 -   To move for a decision, no special action is taken.
 -   When a decision is reached, the review manager ensures the markdown doc is
@@ -306,9 +307,9 @@ If the proposal needs to be checked later to figure out why a decision was made:
 -   The pull request will have edit history publicly visible.
     -   GitHub has a nice renderer for markdown diffs.
 
-##### Pros/Cons
+##### Advantages/Disadvantages
 
-Pros:
+Advantages:
 
 -   No need to convert file formats.
     -   Markdown reviews can be committed directly, putting all history in one
@@ -352,7 +353,7 @@ Neutral:
     -   For other readers, this is likely a pro: the current state of the doc
         remains visible.
 
-Cons:
+Disadvantages:
 
 -   GitHub comments on pull requests can be difficult to find in certain
     situations.
@@ -363,7 +364,7 @@ Cons:
 -   Can't comment on the rendered Markdown, only the raw Markdown.
 -   Images need to be stored separately from the main Markdown file.
     -   Final documentation may or may not need the images; they may only be
-        added to explain the proposal. i.e., this may be extra work without
+        added to explain the proposal. that is, this may be extra work without
         later benefit.
 
 ## Details
@@ -447,7 +448,7 @@ Access controls:
 
 **Decision**: Store proposals in the repository they affect
 
-#### Option: Proposal archive GitHub repo (carbon-proposals)
+#### Option: Proposal archive GitHub repository (carbon-proposals)
 
 In this approach, the review managers are presumed to be responsible for commits
 to the proposal archive.
@@ -456,25 +457,26 @@ Access controls:
 
 -   Commit privileges: review managers
 
-Pros:
+Advantages:
 
 -   Easy to find pending proposals; just look at the carbon-proposals issue
     tracker.
 -   All proposals will be uniquely numbered.
 -   No need for a proposal label: everything's a proposal.
 
-Cons:
+Disadvantages:
 
--   Proposals affect other repos; may miss opportunities to combine changes.
+-   Proposals affect other repositories; may miss opportunities to combine
+    changes.
 -   Harder to filter for proposals that are relevant to a specific repository.
 
 #### Option: Store proposals in the repository they affect
 
 In this approach, we would store proposals in the same repository as they
-affect. e.g., a proposal about the spec would be stored in carbon-lang, while a
-proposal specific to the compiler would be in carbon-toolchains. If a proposal
-affected multiple repositories, we'd probably choose a single primary repository
-for the proposal.
+affect. for example, a proposal about the spec would be stored in carbon-lang,
+while a proposal specific to the compiler would be in carbon-toolchains. If a
+proposal affected multiple repositories, we'd probably choose a single primary
+repository for the proposal.
 
 Specific to a GitHub Markdown-centric flow, we could additionally allow the
 proposal's pull request to include the specific proposed changes to
@@ -497,7 +499,7 @@ Access controls:
 -   Commit privileges: normal repository access, possibly with review managers
     getting broad access in order to finalize proposals.
 
-Pros:
+Advantages:
 
 -   Makes it easier to demonstrate the actual changes a proposal suggests
     making.
@@ -507,17 +509,19 @@ Pros:
     changes_ on a single review thread, for most cases.
 -   Makes it easy to find most/all proposals relevant to a given repository.
 
-Cons:
+Disadvantages:
 
--   Proposals would need to be tracked separately per-repo.
-    -   This could also end up being a pro if we get a bunch of different repos,
-        as it may become easier to find relevant proposals for a given repo.
-        It's only really a con for as long as we have few repos (which may last
-        long-term, as having many repos may lead to other scaling problems).
--   Access controls are part of the parent repo, and so will be less restricted
-    than if we had a separate proposals repo.
+-   Proposals would need to be tracked separately per-repository.
+    -   This could also end up being a pro if we get a bunch of different
+        repositories, as it may become easier to find relevant proposals for a
+        given repository. It's only really a con for as long as we have few
+        repositories (which may last long-term, as having many repositories may
+        lead to other scaling problems).
+-   Access controls are part of the parent repository, and so will be less
+    restricted than if we had a separate proposals repository.
 -   Proposals won't be uniquely numbered.
-    -   We'll need to refer to proposals with the repo, e.g., `carbon-lang/456`.
+    -   We'll need to refer to proposals with the repository, for example,
+        `carbon-lang/456`.
 -   Need to make sure we have a proposal label, to separate from non-proposal
     traffic.
 
@@ -527,8 +531,8 @@ Cons:
 
 #### Common principles
 
--   Proposals will be declared on Discourse Forums at important stages; e.g.,
-    asking for input on ideas, RFC, decisions, etc.
+-   Proposals will be declared on Discourse Forums at important stages; for
+    example, asking for input on ideas, RFC, decisions, etc.
 -   Some discussion is expected to occur on the GitHub PR.
 
 #### Option: Push high-level comments to Discourse Forums
@@ -536,7 +540,7 @@ Cons:
 We could push for high-level comments to be added on the same thread as the
 Discourse Forums RFC.
 
-Pros:
+Advantages:
 
 -   Discourse Forums offer better interfaces for pure, non-code-comment
     discussion.
@@ -547,7 +551,7 @@ Pros:
     -   May also be better for people used to using email lists to discuss
         proposed changes.
 
-Cons:
+Disadvantages:
 
 -   Leads contributors to two different places for comments - some high-level
     discussion will inevitably be in GitHub.
@@ -558,12 +562,12 @@ Cons:
 We could push for high-level comments to be added to the proposal PR, with other
 discussion.
 
-Pros:
+Advantages:
 
 -   The GitHub PR becomes a single hub for conversation.
 -   More familiar for people familiar with GitHub-only workflows.
 
-Cons:
+Disadvantages:
 
 -   Discourse Forum topics cannot have "create" without "reply" permissions, so
     some high-level discussion will inevitably be in Discourse Forums.
@@ -572,7 +576,8 @@ Cons:
 -   Email notifications include only the lines of code affected, not what is
     being replied to. This will generally make it infeasible to get context from
     emails.
--   Comment threads sometimes make it unclear what's being replied to. e.g.,
+-   Comment threads sometimes make it unclear what's being replied to. for
+    example,
     https://github.com/carbon-language/carbon-proposals/pull/5#discussion_r423401993
     and
     ttps://github.com/carbon-language/carbon-proposals/pull/5/files/a51ff951561accfb4aee403d7add6e8e69009ce1#r423401993
@@ -593,16 +598,16 @@ Cons:
 Rather than trying to guide high-level discussion to a particular medium, we
 could offer no guidance.
 
-Pros:
+Advantages:
 
 -   Less policies, more freedom.
     -   Discover what happens, switch back and forth over time based on
         individual contributor preferences.
 
-Cons:
+Disadvantages:
 
--   Pros of a primary hub are discarded. Cons of multiple hubs should be assumed
-    to remain.
+-   Advantages of a primary hub are discarded. Disadvantages of multiple hubs
+    should be assumed to remain.
 
 ### Open question: Should there be a tracking issue?
 
@@ -618,27 +623,27 @@ Cons:
 
 In a workflow where there's always a tracking issue:
 
-1.  Create the tracking issue, e.g. #123.
-2.  Create the PR, e.g. #456, naming the proposal p0123.md after the tracking
-    issue.
+1.  Create the tracking issue, for example #123.
+2.  Create the PR, for example #456, naming the proposal p0123.md after the
+    tracking issue.
     1. Use GitHub features to link #123 and #456.
 3.  Update the status in p0123.md and labels of #123 when progressing a
     proposal.
-4.  When a decision is made, create a new PR, e.g. #789, containing the decision
-    p0123-decision.md.
+4.  When a decision is made, create a new PR, for example #789, containing the
+    decision p0123-decision.md.
     1. This does not replace the Discourse Forum topic announcing a decision.
     2. Use GitHub features to link #123 and #789.
     3. Comments on the decision may go on the decision PR, similar to the
        proposal PR discussion.
 5.  Declined/deferred proposals may be committed or not; it doesn't matter.
 
-Pros:
+Advantages:
 
 -   Easy to find the full decision in p0123-decision.md.
 -   The PR to create the decision is clearly visible in the associated tracking
     issue.
 
-Cons:
+Disadvantages:
 
 -   The tracking issue separates more state.
 
@@ -647,7 +652,7 @@ Cons:
 In a workflow where there's no need for a tracking issue (although contributors
 may create them for bucketing work, they are non-essential):
 
-1.  Create the PR, e.g. #456, naming the proposal p0456.md.
+1.  Create the PR, for example #456, naming the proposal p0456.md.
 2.  Update the labels of #456 when progressing a proposal.
     1. Don't bother putting the status in p0456.md: people should rely on the PR
        labels since it's in the same place.
@@ -659,12 +664,12 @@ may create them for bucketing work, they are non-essential):
 4.  If declined/deferred proposals are committed, it would be best to add a
     status in p0456.md before committing.
 
-Pros:
+Advantages:
 
 -   Lighter weight process: no tracking issue, and no need to update status in
     p0456.md.
 
-Cons:
+Disadvantages:
 
 -   Harder to store the decision in a way that clearly links it to the original
     proposal.
@@ -698,13 +703,13 @@ the PR is abandoned and we at most save a link to it.
 Note that GitHub does (at least to some extent) retain closed PRs, even those
 coming from a fork.
 
-Pros:
+Advantages:
 
 -   The proposals directory remains a list of only accepted proposals.
 -   No need to spend effort saving declined/deferred proposals.
 
 \
-Cons:
+Disadvantages:
 
 -   Lose an easy way to check declined/deferred proposals for history.
     -   More reliance on searching forums for history.
@@ -713,11 +718,11 @@ Cons:
 
 Under this approach, declined/deferred proposals are committed.
 
-Pros:
+Advantages:
 
 -   Easy to skim through declined/deferred proposals.
 
-Cons:
+Disadvantages:
 
 -   Finding accepted proposals may become more difficult.
     -   Could put declined/deferred proposals in a different directory.
@@ -744,8 +749,9 @@ which is for anybody in the community to easily create proposals.
 ### General concern about multiple Markdown flavors
 
 Different markdown implementations have subtly different rendering rules for the
-same input. e.g., per [CommonMark Spec](https://spec.commonmark.org/0.29/#),
-table syntax is not specified, although
+same input. for example, per
+[CommonMark Spec](https://spec.commonmark.org/0.29/#), table syntax is not
+specified, although
 [GitHub uses a table extension](https://guides.github.com/features/mastering-markdown/).
 However, we do plan on using GitHub consistently; this only stands to confuse
 users of other Markdown systems.
@@ -805,11 +811,11 @@ https://gsuite.google.com/marketplace/app/docs_to_markdown/700168918607
 This plugin actually looks pretty good, and may actually work better than
 Google's internal-only equivalent. I'm not seeing obvious downsides.
 
-Pros:
+Advantages:
 
 -   Provides easy conversion of Google Docs to Markdown.
 
-Cons:
+Disadvantages:
 
 -   ?
 
@@ -821,12 +827,12 @@ This is another code formatting tool, but doesn't seem to work as well as
 Google's internal-only equivalent. Google's internal-only equivalent happens to
 do some syntax highlighting, whereas Code blocks does none.
 
-Pros:
+Advantages:
 
 -   Public code formatting.
 -   Works with "Docs to Markdown" plugin to get ```-block escaping.
 
-Cons:
+Disadvantages:
 
 -   Mediocre syntax highlighting for Carbon.
 -   No inline `foo` highlighting, unlike Google's internal-only equivalent.
@@ -839,11 +845,11 @@ https://gsuite.google.com/marketplace/app/advanced_find_replace/11210842879
 Advanced Find & Replace offers more advanced functionality than the built-in
 features, particularly around URL and regexp support.
 
-Pros:
+Advantages:
 
 -   Offers improved functionality around key Google Docs friction problems.
 
-Cons:
+Disadvantages:
 
 -   2 of 5 stars: we should not expect quality.
 -   \$6 purchase price may turn off contributors.
@@ -861,12 +867,12 @@ StackEdit may look good on the surface, but we may effectively be restricted to
 using it as a WYSYWIG markdown editor, not for collaboration. For that, it's
 simply one option amongst many, and not necessarily the best.
 
-Pros:
+Advantages:
 
 -   Provides preview when editing Markdown files.
 -   Provides application-specific comment support.
 
-Cons:
+Disadvantages:
 
 -   Cannot use shared Google workspaces with Google corp accounts, due to
     security restrictions. Will likely cause issues for others, too.

proposals/p0044_decision.md

@@ -78,9 +78,10 @@ etc. In general, the PR-centric model was favored.
     -   No outdated versions in the old format left behind
 
 -   The technical flow seems on balance better than the Google Docs-based
-    workflow. The proposal does a really good job explaining pros and cons. In
-    summary, the Google Docs-centric workflow has a lot of cons that make it
-    difficult to work with proposals over the long term.
+    workflow. The proposal does a really good job explaining advantages and
+    disadvantages. In summary, the Google Docs-centric workflow has a lot of
+    disadvantages that make it difficult to work with proposals over the long
+    term.
 
 ### Rationale for not requiring tracking issues
 

proposals/p0051.md

@@ -91,14 +91,14 @@ While the proposers prefer the first interpretation, the second all-or-nothing
 interpretation may be what's leading to the desire of treating interoperability
 as a higher priority.
 
-Overall, we would present the pros and cons as:
+Overall, we would present the advantages and disadvantages as:
 
-Pros:
+Advantages:
 
 -   There is a consensus that interoperability is critical. Making it the top
     goal emphasizes that.
 
-Cons:
+Disadvantages:
 
 -   While interoperability is critical, the same is true of other goals; this
     isn't enough to determine priority.
@@ -167,11 +167,11 @@ The project goals could be addressed as-is in the proposal.
 
 We could completely remove the project goals from this document.
 
-Pros:
+Advantages:
 
 -   Allows this to be the "language goals" document.
 
-Cons:
+Disadvantages:
 
 -   Creates additional documents that need to be understood to parse language
     goals.
@@ -182,11 +182,11 @@ Cons:
 
 We could make the project goals part of the priority list.
 
-Pros:
+Advantages:
 
 -   Makes the ordering unambiguous.
 
-Cons:
+Disadvantages:
 
 -   Makes what's currently a numerated list of language design goals less
     design-focused.
@@ -199,14 +199,14 @@ Cons:
 Originally, we only had one goals and priorities section. We could re-merge
 project goals and language goals.
 
-Pros:
+Advantages:
 
 -   Makes the document shorter and more concise.
 -   Tooling can already be considered a priority under "Code that is easy to
     read, understand, and write", and is explicitly mentioned as part of that
     goal.
 
-Cons:
+Disadvantages:
 
 -   Previous setup raised objections over why the community goal wasn't part of
     the priority list.

proposals/p0083.md

@@ -79,12 +79,12 @@ We also considered putting the full design overview in one file, as in
 [PR 22](https://github.com/carbon-language/carbon-lang/pull/22). This is versus
 the hierarchy proposed here.
 
-Pros:
+Advantages:
 
 -   All proposed changes are in one place.
 -   Easier for people to skim rationale and considered changes.
 
-Cons:
+Disadvantages:
 
 -   Encourages more single-file designs.
     -   A principle of the multi-file approach is that complex features may have
@@ -99,13 +99,13 @@ The primary alternative is to avoid even having a draft or in-progress design of
 this form until each constituent component is more thoroughly conceived and
 considered.
 
-Pros:
+Advantages:
 
 -   Avoids anchoring design on approaches that haven't yet been fully explored.
     -   Avoids getting stuck on discussing details where a proposal isn't
         fleshed out.
 
-Cons:
+Disadvantages:
 
 -   The lack of an overview can lead to significant confusion and
     inconsistencies in discussion, hindering fleshing out details.
@@ -131,13 +131,13 @@ additional content.
 The proposed approach assumes that the proposed overviews offer significant
 value for ramp-up.
 
-Pros:
+Advantages:
 
 -   Eliminates content duplication.
 -   A simple index is easier to maintain long-term, with less to become stale.
     -   It could be fully automated.
 
-Cons:
+Disadvantages:
 
 -   No quick way to get a high-level understanding.
     -   The overview is the only step before "reading every design".

proposals/p0107.md

@@ -103,7 +103,7 @@ Keep `package`.
 Right now, the `package` syntax requires the package's own name be repeated
 through code. This touches on a couple alternatives:
 
--   Strict association between the filesystem path and library/namespace
+-   Strict association between the file system path and library/namespace
 -   [Referring to the package as `package`](/docs/design/code_and_name_organization.md#referring-to-the-package-as-package)
 
 The end result of taking both alternatives would be that:

proposals/p0142.md

@@ -83,7 +83,7 @@ Regardless of how program text is concretely stored, the first step in
 processing any such text is to convert it to a sequence of Unicode code points
 -- although such conversion may be purely notional. The result of this
 conversion is a Carbon _source file_. Depending on the needs of the language, we
-may require each such source file to have an associated file name, even if the
+may require each such source file to have an associated filename, even if the
 source file does not originate in anything resembling a file system.
 
 ### Normalization
@@ -153,7 +153,7 @@ permitted in identifiers in C++20. Similarly, it indicates which characters
 should be classified as whitespace, including all the ASCII whitespace
 characters plus some non-ASCII whitespace characters. It also supports
 language-specific "profiles" to alter these baseline character sets for the
-needs of a particular language -- for instance, to permit underscores in
+needs of a particular language -- for example, to permit underscores in
 identifiers, or to include non-breaking spaces as whitespace characters.
 
 This proposal does not specify concrete choices for lexical rules, nor that we

proposals/p0149.md

@@ -116,6 +116,8 @@ https://docs.microsoft.com/en-us/style-guide/welcome/
 > may be that Microsoft has other noteworthy guidance for terms that Google
 > doesn't.
 
+<!-- google-doc-style-ignore -->
+
 above
 
 : Google: Use preceding.
@@ -296,6 +298,8 @@ vs.
 
 : Microsoft: Use versus.
 
+<!-- google-doc-style-resume -->
+
 ## Alternatives considered
 
 Various offline resources like the Chicago Manual of Style may be helpful to