Corrections and refinements for user documentation. (apple#35)

Author: jglogan

BUILDING.md

@@ -1,9 +1,9 @@
 # Building the project
 
-To build the Containerization package, your system needs either:
+To build the `container` project, your system needs either:
 
-- macOS 15 or newer and Xcode 17 beta.
-- macOS 16 Developer Preview.
+- macOS Sequoia 15 or newer and Xcode 17 beta.
+- macOS Developer Preview.
 
 ## Compile and test
 
@@ -39,7 +39,7 @@ To make changes to `container` that require changes to the Containerization proj
     cd container
     ```
 
-3. If the application services are already running, stop them. 
+3. If the `container` services are already running, stop them. 
 
     ```
     bin/container system stop
@@ -52,10 +52,10 @@ To make changes to `container` that require changes to the Containerization proj
     swift package update containerization
     ```
 
-5. Build the init filesystem for your local copy of containerization.
+5. Build the init filesystem for your local copy of the Containerization project.
 
     ```
-    (cd ../swiftcontainerization && make clean all)
+    (cd ${CONTAINERIZATION_PATH} && make clean all)
     ```
 
 6. Build `container`.
@@ -64,7 +64,7 @@ To make changes to `container` that require changes to the Containerization proj
     make clean all
     ```
 
-7. Start the application services.
+7. Start the `container` services.
 
     ```
     bin/container system start
@@ -85,7 +85,7 @@ To revert to using the Containerization dependency from your `Package.swift`:
     make clean all
     ```
 
-3. Restart application services.
+3. Restart the `container` services.
 
     ```
     bin/container system restart

README.md

@@ -1,25 +1,25 @@
 
 # `container`
 
-`container` is an application that you can use to create and run Linux containers as lightweight virtual machines on your Mac. It's written in Swift, and optimized for Apple silicon. 
+`container` is a tool that you can use to create and run Linux containers as lightweight virtual machines on your Mac. It's written in Swift, and optimized for Apple silicon. 
 
-The application consumes and produces OCI-compliant container images, so you can pull and run images from any standard container registry. You can push images that you build to those registries as well, and run the images in any other OCI-compliant application.
+The tool consumes and produces OCI-compliant container images, so you can pull and run images from any standard container registry. You can push images that you build to those registries as well, and run the images in any other OCI-compliant application.
 
-`container` uses the [Containerization](https://github.com/apple/containerization) Swift package for low level container, image and process management.
+`container` uses the [Containerization](https://github.com/apple/containerization) Swift package for low level container, image, and process management.
 
 ![introductory movie showing some basic commands](./docs/assets/landing-movie.gif)
 
 ## Get started
 
-Install the `container` application on your Mac.
+Install `container` on your Mac.
 
 ### Requirements
 
-You need an Apple silicon Mac to run `container`. To build the application, see the [BUILDING](./BUILDING.md) document.
+You need an Apple silicon Mac to run `container`. To build it, see the [BUILDING](./BUILDING.md) document.
 
-`container` is designed to take advantage of the features of the macOS 16 Developer Preview. You can run the application on macOS Sequoia, but the `container` maintainers typically will not address Sequoia issues that cannot be reproduced on the macOS 16 Developer Preview.
+`container` is designed to use the new features in the macOS Developer Preview. You can run the tool on macOS Sequoia 15, but the `container` maintainers typically will not address issues discovered on macOS Sequoia 15 that cannot be reproduced on the macOS Developer Preview.
 
-There are [significant networking limitations](https://github.com/apple/container#macos-sequoia-limitations) that impact the usability `container` on macOS Sequoia.
+There are [significant networking limitations](/docs/technical-overview.md#macos-sequoia-15-limitations) that impact the usability `container` on macOS Sequoia 15.
 
 ### Install or upgrade
 
@@ -29,13 +29,13 @@ If you're upgrading, first uninstall your existing `container` while preserving
 uninstall-container.sh -k
 ```
 
-Download the latest application installer package from the [Github release page](https://github.com/apple/container/releases).
+Download the latest installer package for `container` from the [Github release page](https://github.com/apple/container/releases).
 
-To install the application, double click the package file and follow the instructions. Enter your administrator password when prompted to give the installer permission to place the application under `/usr/local`.
+To install the tool, double click the package file and follow the instructions. Enter your administrator password when prompted, to give the installer permission to place the installed files under `/usr/local`.
 
 ### Uninstall
 
-Use the `uninstall-container.sh` script to remove the application from your system. To remove your user data along with the application, run:
+Use the `uninstall-container.sh` script to remove `container` from your system. To remove your user data along with the tool, run:
 
 ```bash
 uninstall-container.sh -d
@@ -52,8 +52,8 @@ uninstall-container.sh -k
 - Take [a guided tour of `container`](./docs/tutorial.md) by building, running, and publishing a simple web server image.
 - Learn how to [use various `container` features](./docs/how-to.md).
 - Read a brief description and [technical overview](./docs/technical-overview.md) of `container`.
+- View the project [API documentation](https://pages.github.com/apple/container/).
 
 ## Contributing
 
-Contributions to Containerization are welcomed and encouraged. Please see our [main contributing guide](https://github.com/apple/containerization/blob/main/CONTRIBUTING.md) for more information.
-
+Contributions to `container` are welcomed and encouraged. Please see our [main contributing guide](https://github.com/apple/containerization/blob/main/CONTRIBUTING.md) for more information.

docs/how-to.md

@@ -4,15 +4,15 @@ How to use the features of `container`.
 
 ## Configure memory and CPUs for your containers
 
-Since the containers created by `container` are lightweight virtual machines, you need to consider the needs of your containerized application when you `container run` a container.  The `--memory` and `--cpus` options allow you to override the default memory and CPU limits for the virtual machine. The default values are 1 gigabyte of RAM and 4 CPUs. You can use abbreviations for memory units; for example, to run a container for image `big` with 8 CPUs and 32 gigabytes of memory, use:
+Since the containers created by `container` are lightweight virtual machines, consider the needs of your containerized application when you use `container run`.  The `--memory` and `--cpus` options allow you to override the default memory and CPU limits for the virtual machine. The default values are 1 gigabyte of RAM and 4 CPUs. You can use abbreviations for memory units; for example, to run a container for image `big` with 8 CPUs and 32 gigabytes of memory, use:
 
 ```bash
 container run --rm --cpus 8 --memory 32g big
 ```
 
 ## Configure memory and CPUs for large builds
 
-When you first run `container build`, `container` starts a *builder*, which is a utility container that performs image build. As with anything you run with `container run`, the builder runs in a lightweight virtual machine, so for resource-intensive builds, you may need to increase the memory and CPU limits for the builder VM.
+When you first run `container build`, `container` starts a *builder*, which is a utility container that builds images from your `Dockerfile`s. As with anything you run with `container run`, the builder runs in a lightweight virtual machine, so for resource-intensive builds, you may need to increase the memory and CPU limits for the builder VM.
 
 By default, the builder VM receives 2 gigabytes of RAM and 2 CPUs. You can change these limits by starting the builder container before running `container build`:
 
@@ -46,7 +46,7 @@ total 4
 
 The argument to `--volume` in the example consists of the full pathname for the host folder and the full pathname for the mount point in the container, separated by a colon.
 
-The `--mount` option uses a comma separated `key=value` syntax to achieve the same result:
+The `--mount` option uses a comma-separated `key=value` syntax to achieve the same result:
 
 ```shellsession
 % container run --mount source=${HOME}/Desktop/assets,target=/content/assets docker.io/python:slim ls -l /content/assets
@@ -57,9 +57,9 @@ total 4
 
 ## Build and run a multiplatform image
 
-Using the [project from the tutorial example](/documentation/tutorial/#set-up-a-simple-project), you can create an image to use both on Apple Silicon Macs and on AMD64 servers.
+Using the [project from the tutorial example](/documentation/tutorial/#set-up-a-simple-project), you can create an image to use both on Apple silicon Macs and on x86-64 servers.
 
-When building the image, just add `--arch` options that directs the builder to create an image supporting both the `arm64` and `amd64` architectures:
+When building the image, just add `--arch` options that direct the builder to create an image supporting both the `arm64` and `amd64` architectures:
 
 ```bash
 container build --arch arm64 --arch amd64 --tag registry.example.com/fido/web-test:latest --file Dockerfile .
@@ -73,7 +73,7 @@ Linux 7932ce5f-ec10-4fbe-a2dc-f29129a86b64 6.1.68 #1 SMP Mon Mar 31 18:27:51 UTC
 %
 ```
 
-When you run the command with the `amd64` architecture, the AMD64 version of `uname` of Python using Rosetta translation, so that you will see information for an AMD64 system:
+When you run the command with the `amd64` architecture, the x86-64 version of `uname` runs under Rosetta translation, so that you will see information for an x86-64 system:
 
 ```shellsession
 container run --arch amd64 --rm registry.example.com/fido/web-test:latest uname -a