@@ -225,7 +225,8 @@ uploaded context. The builder reference contains detailed information on

     $ docker build -t vieux/apache:2.0 .

 This will build like the previous example, but it will then tag the resulting

-image. The repository name will be `vieux/apache` and the tag will be `2.0`

+image. The repository name will be `vieux/apache` and the tag will be `2.0`.

+[Read more about valid tags](tag.md).

 You can apply multiple tags to an image. For example, you can apply the `latest`

 tag to a newly built image and add another tag that references a specific

@@ -24,6 +24,7 @@ It can be useful to commit a container's file changes or settings into a new

 image. This allows you debug a container by running an interactive shell, or to

 export a working dataset to another server. Generally, it is better to use

 Dockerfiles to manage your images in a documented and maintainable way.

+[Read more about valid image names and tags](tag.md).

 The commit operation will not include any data contained in

 volumes mounted inside the container.

@@ -19,6 +19,7 @@ parent = "smn_cli"

 Use `docker push` to share your images to the [Docker Hub](https://hub.docker.com)

 registry or to a self-hosted one.

+[Read more about valid image names and tags](tag.md).

 Killing the `docker push` process, for example by pressing `CTRL-c` while it is

 running in a terminal, will terminate the push operation.

@@ -10,11 +10,57 @@ parent = "smn_cli"

 # tag

-    Usage: docker tag [OPTIONS] IMAGE[:TAG] [REGISTRYHOST/][USERNAME/]NAME[:TAG]

+    Usage: docker tag [OPTIONS] NAME[:TAG] NAME[:TAG]

     Tag an image into a repository

       --help               Print usage

+An image name is made up of slash-separated name components, optionally prefixed

+by a registry hostname. The hostname must comply with standard DNS rules, but

+may not contain underscores. If a hostname is present, it may optionally be

+followed by a port number in the format `:8080`. If not present, the command 

+uses Docker's public registry located at `registry-1.docker.io` by default. Name 

+components may contain lowercase characters, digits and separators. A separator 

+is defined as a period, one or two underscores, or one or more dashes. A name 

+component may not start or end with a separator.

+

+A tag name may contain lowercase and uppercase characters, digits, underscores,

+periods and dashes. A tag name may not start with a period or a dash and may

+contain a maximum of 128 characters.

+

 You can group your images together using names and tags, and then upload them

 to [*Share Images via Repositories*](../../userguide/containers/dockerrepos.md#contributing-to-docker-hub).

+

+# Examples

+

+## Tagging an image referenced by ID

+

+To tag a local image with ID "0e5574283393" into the "fedora" repository with 

+"version1.0":

+

+    docker tag 0e5574283393 fedora/httpd:version1.0

+

+## Tagging an image referenced by Name

+

+To tag a local image with name "httpd" into the "fedora" repository with 

+"version1.0":

+

+    docker tag httpd fedora/httpd:version1.0

+

+Note that since the tag name is not specified, the alias is created for an

+existing local version `httpd:latest`.

+

+## Tagging an image referenced by Name and Tag

+

+To tag a local image with name "httpd" and tag "test" into the "fedora"

+repository with "version1.0.test":

+

+    docker tag httpd:test fedora/httpd:version1.0.test

+

+## Tagging an image for a private repository

+

+To push an image to a private registry and not the central Docker

+registry you must tag it with the registry hostname and port (if needed).

+

+    docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0

@@ -91,7 +91,9 @@ set as the **URL**, the repository is cloned locally and then sent as the contex

    Remove intermediate containers after a successful build. The default is *true*.

 **-t**, **--tag**=""

-   Repository names (and optionally with tags) to be applied to the resulting image in case of success.

+   Repository names (and optionally with tags) to be applied to the resulting 

+   image in case of success. Refer to **docker-tag(1)** for more information

+   about valid tag names.

 **-m**, **--memory**=*MEMORY*

   Memory limit

@@ -16,7 +16,8 @@ CONTAINER [REPOSITORY[:TAG]]

 # DESCRIPTION

 Create a new image from an existing container specified by name or

 container ID.  The new image will contain the contents of the

-container filesystem, *excluding* any data volumes.

+container filesystem, *excluding* any data volumes. Refer to **docker-tag(1)**

+for more information about valid image and tag names.

 While the `docker commit` command is a convenient way of extending an

 existing image, you should prefer the use of a Dockerfile and `docker

@@ -13,7 +13,8 @@ NAME[:TAG] | [REGISTRY_HOST[:REGISTRY_PORT]/]NAME[:TAG]

 This command pushes an image or a repository to a registry. If you do not

 specify a `REGISTRY_HOST`, the command uses Docker's public registry located at

-`registry-1.docker.io` by default. 

+`registry-1.docker.io` by default. Refer to **docker-tag(1)** for more 

+information about valid image and tag names.

 # OPTIONS

 **--help**

@@ -7,44 +7,59 @@ docker-tag - Tag an image into a repository

 # SYNOPSIS

 **docker tag**

 [**--help**]

-IMAGE[:TAG] [REGISTRY_HOST/][USERNAME/]NAME[:TAG]

+NAME[:TAG] NAME[:TAG]

 # DESCRIPTION

 Assigns a new alias to an image in a registry. An alias refers to the

 entire image name including the optional `TAG` after the ':'. 

-If you do not specify a `REGISTRY_HOST`, the command uses Docker's public

-registry located at `registry-1.docker.io` by default. 

-

 # "OPTIONS"

 **--help**

    Print usage statement.

-**REGISTRY_HOST**

-   The hostname of the registry if required. This may also include the port

-separated by a ':'

-

-**USERNAME**

-   The username or other qualifying identifier for the image.

-

 **NAME**

-   The image name.

+   The image name which is made up of slash-separated name components, 

+   optionally prefixed by a registry hostname. The hostname must comply with 

+   standard DNS rules, but may not contain underscores. If a hostname is 

+   present, it may optionally be followed by a port number in the format 

+   `:8080`. If not present, the command uses Docker's public registry located at

+   `registry-1.docker.io` by default. Name components may contain lowercase 

+   characters, digits and separators. A separator is defined as a period, one or 

+   two underscores, or one or more dashes. A name component may not start or end 

+   with a separator.

 **TAG**

-   The tag you are assigning to the image.  Though this is arbitrary it is

-recommended to be used for a version to distinguish images with the same name.

-Also, for consistency tags should only include a-z0-9-_. .

-Note that here TAG is a part of the overall name or "tag".

+   The tag assigned to the image to version and distinguish images with the same

+   name. The tag name may contain lowercase and uppercase characters, digits, 

+   underscores, periods and dashes. A tag name may not start with a period or a 

+   dash and may contain a maximum of 128 characters.

 # EXAMPLES

-## Giving an image a new alias

+## Tagging an image referenced by ID

-Here is an example of aliasing an image (e.g., 0e5574283393) as "httpd" and 

-tagging it into the "fedora" repository with "version1.0":

+To tag a local image with ID "0e5574283393" into the "fedora" repository with 

+"version1.0":

     docker tag 0e5574283393 fedora/httpd:version1.0

+## Tagging an image referenced by Name

+

+To tag a local image with name "httpd" into the "fedora" repository with 

+"version1.0":

+

+    docker tag httpd fedora/httpd:version1.0

+

+Note that since the tag name is not specified, the alias is created for an

+existing local version `httpd:latest`.

+

+## Tagging an image referenced by Name and Tag

+

+To tag a local image with name "httpd" and tag "test" into the "fedora"

+repository with "version1.0.test":

+

+    docker tag httpd:test fedora/httpd:version1.0.test

+

 ## Tagging an image for a private repository

 To push an image to a private registry and not the central Docker