Document protocol usage for --publish

This also unifies the documentation of `--publish` for `podman create`, `podman run`, and `podman pod create`.

Signed-off-by: Daniel Rudolf <github.com@daniel-rudolf.de>

1 files changed, 20 insertions, 6 deletions

diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md
index cf749efda..1a98528bb 100644
--- a/docs/source/markdown/podman-pod-create.1.md
+++ b/docs/source/markdown/podman-pod-create.1.md
@@ -227,16 +227,30 @@ Set the PID mode for the pod. The default is to create a private PID namespace f
 
 Write the pod ID to the file.
 
-#### **--publish**=*port*, **-p**
+#### **--publish**, **-p**=[[_ip_:][_hostPort_]:]_containerPort_[/_protocol_]
 
-Publish a port or range of ports from the pod to the host.
+Publish a container's port, or range of ports, within this pod to the host.
 
-Format: `ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort`
 Both hostPort and containerPort can be specified as a range of ports.
-When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range.
-Use `podman port` to see the actual mapping: `podman port CONTAINER $CONTAINERPORT`.
+When specifying ranges for both, the number of container ports in the
+range must match the number of host ports in the range.
 
-NOTE: This cannot be modified once the pod is created.
+If host IP is set to 0.0.0.0 or not set at all, the port will be bound on all IPs on the host.
+
+By default, Podman will publish TCP ports. To publish a UDP port instead, give
+`udp` as protocol. To publish both TCP and UDP ports, set `--publish` twice,
+with `tcp`, and `udp` as protocols respectively. Rootful containers can also
+publish ports using the `sctp` protocol.
+
+Host port does not have to be specified (e.g. `podman run -p 127.0.0.1::80`).
+If it is not, the container port will be randomly assigned a port on the host.
+
+Use **podman port** to see the actual mapping: `podman port $CONTAINER $CONTAINERPORT`.
+
+**Note:** You must not publish ports of containers in the pod individually,
+but only by the pod itself.
+
+**Note:** This cannot be modified once the pod is created.
 
 #### **--replace**