docs: Rearrange options on build-container-image manual page to match --help

Author: euanh

Sources/swift-container-plugin/Documentation.docc/build-container-image.md

@@ -8,7 +8,7 @@ Wrap a binary in a container image and publish it.
 
 ### Usage
 
-`swift package build-container-image [<options>] --repository <repository>`
+`swift package build-container-image [<options>]`
 
 ### Options
 
@@ -17,22 +17,47 @@ Wrap a binary in a container image and publish it.
 
   If `Package.swift` defines only one product, it will be selected by default.
 
+### Source and destination repository options
+
 - term  `--default-registry <default-registry>`:
   The default registry hostname. (default: `docker.io`)
 
   If the repository path does not contain a registry hostname, the default registry will be prepended to it.
 
 - term  `--repository <repository>`:
-  The repository path.
+  Destination image repository.
 
-  If the path does not begin with a registry hostname, the default registry will be prepended to the path.
+  If the repository path does not begin with a registry hostname, the default registry will be prepended to the path.
+  The destination repository must be specified, either by setting the `--repository` option or the `CONTAINERTOOL_REPOSITORY` environment variable.
+
+- term  `--tag <tag>`:
+  Destination image tag.
+
+  The `latest` tag is automatically updated to refer to the published image.
+
+- term  `--from <from>`:
+  Base image reference. (default: `swift:slim`)
+
+### Image build options
 
 - term  `--resources <resources>`:
   Add the file or directory at `resources` to the image.
   Directories are added recursively.
 
   If the `product` being packaged has a [resource bundle](https://developer.apple.com/documentation/xcode/bundling-resources-with-a-swift-package) it will be added to the image automatically.
 
+### Image configuration options
+
+- term  `--architecture <architecture>`:
+  CPU architecture required to run the image.
+
+  If the base image is `scratch`, the final image will have no base layer and will consist only of the application layer and resource bundle layer, if the product has a resource bundle.
+
+- term  `--os <os>`:
+  Operating system required to run the image. (default: `linux`)
+
+### Authentication options
+
 - term  `--default-username <username>`:
   Default username to use when logging into the registry.
 
@@ -45,34 +70,20 @@ Wrap a binary in a container image and publish it.
   This password is used if there is no matching `.netrc` entry for the registry, there is no `.netrc` file, or the `--disable-netrc` option is set.
   The same password is used for the source and destination registries.
 
-- term  `-v, --verbose`:
-  Verbose output.
-
-- term  `--allow-insecure-http <allow-insecure-http>`:
-  Connect to the container registry using plaintext HTTP. (values: `source`, `destination`, `both`)
-
-- term  `--architecture <architecture>`:
-  CPU architecture to record in the image.
-
-- term  `--from <from>`:
-  Base image reference. (default: `swift:slim`)
-
-  If the base image is `scratch`, the final image will have no base layer and will consist only of the application layer and resource bundle layer, if the product has a resource bundle.
-
-- term  `--os <os>`:
-  Operating system to record in the image. (default: `linux`)
-
-- term  `--tag <tag>`:
-  Tag for this manifest.
-
-  The `latest` tag is automatically updated to refer to the published image.
-
 - term  `--enable-netrc/--disable-netrc`:
   Load credentials from a netrc file (default: `--enable-netrc`)
 
 - term  `--netrc-file <netrc-file>`:
   The path to the `.netrc` file.
 
+- term  `--allow-insecure-http <allow-insecure-http>`:
+  Connect to the container registry using plaintext HTTP. (values: `source`, `destination`, `both`)
+
+### Options
+
+- term  `-v, --verbose`:
+  Verbose output.
+
 - term  `-h, --help`:
   Show help information.
 
@@ -83,14 +94,15 @@ Wrap a binary in a container image and publish it.
   (default: `docker.io`)
 
 - term `CONTAINERTOOL_REPOSITORY`:
-  The repository path.
+  The destination image repository.
 
   If the path does not begin with a registry hostname, the default registry will be prepended to the path.
+  The destination repository must be specified, either by setting the `--repository` option or the `CONTAINERTOOL_REPOSITORY` environment variable.
 
 - term `CONTAINERTOOL_BASE_IMAGE`:
   Base image on which to layer the application.
   (default: `swift:slim`)
 
 - term `CONTAINERTOOL_OS`:
-  Operating system to encode in the container image.
+  Operating system.
   (default: `Linux`)