containers
/
image
mirror of https://github.com/containers/image.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fix font choices in containers-transports.5 

Consistently:
- Literal strings are in `backticks`
- Variables are _italic in underscores_
- Syntax meta-characters []{} are neither

This does not really work well in section headings, but at least the
detailed descriptions should now be less misleading.

Fixes #2378.

Signed-off-by: Miloslav Trmač <mitr@redhat.com>
This commit is contained in:
Miloslav Trmač 2024-05-13 18:26:53 +02:00
parent 9318d0eaaf
commit 3a276e194a
1 changed files with 20 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
docs/containers-transports.5.md
View File

@ -9,7 +9,7 @@ containers-transports - description of supported transports for copying and stor
## DESCRIPTION
Tools which use the containers/image library, including skopeo(1), buildah(1), podman(1), all share a common syntax for referring to container images in various locations.
The general form of the syntax is _transport:details_, where details are dependent on the specified transport, which are documented below.
The general form of the syntax is _transport_`:`_details_, where details are dependent on the specified transport, which are documented below.
The semantics of the image names ultimately depend on the environment where
they are evaluated. For example: if evaluated on a remote server, image names
@ -18,14 +18,14 @@ directory of the image consumer.
<!-- atomic: is deprecated and not documented here. -->
### **containers-storage**:[**[**storage-specifier**]**]{image-id|docker-reference[@image-id]}
### **containers-storage:**[**[**_storage-specifier_**]**]{_image-id_|_docker-reference_[**@**_image-id_]}
An image located in a local containers storage.
The format of _docker-reference_ is described in detail in the **docker** transport.
The _storage-specifier_ allows for referencing storage locations on the file system and has the format `[[driver@]root[+run-root][:options]]` where the optional `driver` refers to the storage driver (e.g., overlay or btrfs) and where `root` is an absolute path to the storage's root directory.
The optional `run-root` can be used to specify the run directory of the storage where all temporary writable content is stored.
The optional `options` are a comma-separated list of driver-specific options.
The _storage-specifier_ allows for referencing storage locations on the file system and has the format `[`[_driver_`@`]_root_[`+`_run-root_][`:`_options_]`]` where the optional _driver_ refers to the storage driver (e.g., `overlay` or `btrfs`) and where _root_ is an absolute path to the storage's root directory.
The optional _run-root_ can be used to specify the run directory of the storage where all temporary writable content is stored.
The optional _options_ are a comma-separated list of driver-specific options.
Please refer to containers-storage.conf(5) for further information on the drivers and supported options.
### **dir:**_path_
@ -40,34 +40,34 @@ By default, uses the authorization state in `$XDG_RUNTIME_DIR/containers/auth.js
If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using docker-login(1).
The containers-registries.conf(5) further allows for configuring various settings of a registry.
Note that a _docker-reference_ has the following format: _name_[**:**_tag_ | **@**_digest_].
Note that a _docker-reference_ has the following format: _name_[`:`_tag_ | `@`_digest_].
While the docker transport does not support both a tag and a digest at the same time some formats like containers-storage do.
Digests can also be used in an image destination as long as the manifest matches the provided digest.
The docker transport supports pushing images without a tag or digest to a registry when the image name is suffixed with **@@unknown-digest@@**. The _name_**@@unknown-digest@@** reference format cannot be used with a reference that has a tag or digest.
The docker transport supports pushing images without a tag or digest to a registry when the image name is suffixed with `@@unknown-digest@@`. The _name_`@@unknown-digest@@` reference format cannot be used with a reference that has a tag or digest.
The digest of images can be explored with skopeo-inspect(1).
If `name` does not contain a slash, it is treated as `docker.io/library/name`.
Otherwise, the component before the first slash is checked if it is recognized as a `hostname[:port]` (i.e., it contains either a . or a :, or the component is exactly localhost).
If the first component of name is not recognized as a `hostname[:port]`, `name` is treated as `docker.io/name`.
If _name_ does not contain a slash, it is treated as `docker.io/library/`_name_.
Otherwise, the component before the first slash is checked if it is recognized as a _hostname_[`:`_port_] (i.e., it contains either a `.` or a `:`, or the component is exactly `localhost`).
If the first component of name is not recognized as a _hostname_[`:`_port_], _name_ is treated as `docker.io/`_name_.
### **docker-archive:**_path[:{docker-reference|@source-index}]_
### **docker-archive:**_path_[`:`{_docker-reference_|`@`_source-index_}]
An image is stored in the docker-save(1) formatted file.
_docker-reference_ must not contain a digest.
Alternatively, for reading archives, @_source-index_ is a zero-based index in archive manifest
Alternatively, for reading archives, `@`_source-index_ is a zero-based index in archive manifest
(to access untagged images).
If neither _docker-reference_ nor @_source_index is specified when reading an archive, the archive must contain exactly one image.
If neither _docker-reference_ nor `@`_source_index is specified when reading an archive, the archive must contain exactly one image.
The _path_ can refer to a stream, e.g. `docker-archive:/dev/stdin`.
### **docker-daemon:**_docker-reference|algo:digest_
### **docker-daemon:**_docker-reference_|_algo_`:`_digest_
An image stored in the docker daemon's internal storage.
The image must be specified as a _docker-reference_ or in an alternative _algo:digest_ format when being used as an image source.
The _algo:digest_ refers to the image ID reported by docker-inspect(1).
The image must be specified as a _docker-reference_ or in an alternative _algo_`:`_digest_ format when being used as an image source.
The _algo_`:`_digest_ refers to the image ID reported by docker-inspect(1).
### **oci:**_path[:reference]_
### **oci:**_path_[`:`_reference_]
An image in a directory structure compliant with the "Open Container Image Layout Specification" at _path_.
@ -75,7 +75,7 @@ The _path_ value terminates at the first `:` character; any further `:` characte
The _reference_ is used to set, or match, the `org.opencontainers.image.ref.name` annotation in the top-level index.
If _reference_ is not specified when reading an image, the directory must contain exactly one image.
### **oci-archive:**_path[:reference]_
### **oci-archive:**_path_[`:`_reference_]
An image in a tar(1) archive with contents compliant with the "Open Container Image Layout Specification" at _path_.
@ -83,10 +83,10 @@ The _path_ value terminates at the first `:` character; any further `:` characte
The _reference_ is used to set, or match, the `org.opencontainers.image.ref.name` annotation in the top-level index.
If _reference_ is not specified when reading an archive, the archive must contain exactly one image.
### **ostree:**_docker-reference[@/absolute/repo/path]_
### **ostree:**_docker-reference_[`@`_/absolute/repo/path_]
An image in the local ostree(1) repository.
_/absolute/repo/path_ defaults to _/ostree/repo_.
_/absolute/repo/path_ defaults to `/ostree/repo`.
### **sif:**_path_