Merge pull request #8449 from vrothberg/top-docs

[CI:DOCS] clarify ps(1) fallback of `podman top`

cmd/podman/containers/top.go

@@ -18,12 +18,10 @@ import (
 )
 
 var (
-	topDescription = `Similar to system "top" command.
-
-  Specify format descriptors to alter the output.
-
-  Running "podman top -l pid pcpu seccomp" will print the process ID, the CPU percentage and the seccomp mode of each process of the latest container.`
+	topDescription = `Display the running processes of a container.
 
+  The top command extends the ps(1) compatible AIX descriptors with container-specific ones as shown below.  In the presence of ps(1) specific flags (e.g, -eo), Podman will execute ps(1) inside the container.
+`
 	topOptions = entities.TopOptions{}
 
 	topCommand = &cobra.Command{

docs/source/markdown/podman-top.1.md

@@ -9,7 +9,7 @@ podman\-top - Display the running processes of a container
 **podman container top** [*options*] *container* [*format-descriptors*]
 
 ## DESCRIPTION
-Display the running processes of the container. The *format-descriptors* are ps (1) compatible AIX format descriptors but extended to print additional information, such as the seccomp mode or the effective capabilities of a given process. The descriptors can either be passed as separated arguments or as a single comma-separated argument. Note that you can also specify options and or flags of ps(1); in this case, Podman will fallback to executing ps with the specified arguments and flags in the container.
+Display the running processes of the container. The *format-descriptors* are ps (1) compatible AIX format descriptors but extended to print additional information, such as the seccomp mode or the effective capabilities of a given process. The descriptors can either be passed as separated arguments or as a single comma-separated argument. Note that you can also specify options and or flags of ps(1); in this case, Podman will fallback to executing ps with the specified arguments and flags in the container.  Please use the "h*" descriptors if you want to extract host-related information.  For instance, `podman top $name hpid huser` to display the PID and user of the processes in the host context.
 
 ## OPTIONS