Re-implement --before and --since as options for --filter

* This commit will mark --before and --since as deprecated, but leave their behavior
  unchanged until they are removed, then re-implement them as options for --filter.

* And update the related docs.

* Update the integration tests.

Fixes issue #17716

Signed-off-by: Wen Cheng Ma <wenchma@cn.ibm.com>

docs/reference/commandline/ps.md

@@ -15,16 +15,14 @@ parent = "smn_cli"
     List containers
 
       -a, --all=false       Show all containers (default shows just running)
-      --before=""           Show only container created before Id or Name
       -f, --filter=[]       Filter output based on conditions provided
       --format=[]           Pretty-print containers using a Go template
       --help=false          Print usage
-      -l, --latest=false    Show the latest created container, include non-running
-      -n=-1                 Show n last created containers, include non-running
+      -l, --latest=false    Show the latest created container (includes all states)
+      -n=-1                 Show n last created containers (includes all states)
       --no-trunc=false      Don't truncate output
       -q, --quiet=false     Only display numeric IDs
       -s, --size=false      Display total file sizes
-      --since=""            Show created since Id or Name, include non-running
 
 Running `docker ps --no-trunc` showing 2 linked containers.
 

man/docker-ps.1.md

@@ -7,7 +7,6 @@ docker-ps - List containers
 # SYNOPSIS
 **docker ps**
 [**-a**|**--all**[=*false*]]
-[**--before**[=*BEFORE*]]
 [**-f**|**--filter**[=*[]*]]
 [**--format**=*"TEMPLATE"*]
 [**--help**]
@@ -16,7 +15,6 @@ docker-ps - List containers
 [**--no-trunc**[=*false*]]
 [**-q**|**--quiet**[=*false*]]
 [**-s**|**--size**[=*false*]]
-[**--since**[=*SINCE*]]
 
 # DESCRIPTION
 
@@ -27,9 +25,6 @@ the running containers.
 **-a**, **--all**=*true*|*false*
    Show all containers. Only running containers are shown by default. The default is *false*.
 
-**--before**=""
-   Show only containers created before Id or Name, including non-running containers.
-
 **-f**, **--filter**=[]
    Provide filter values. Valid filters:
                           exited=<int> - containers with exit code of <int>
@@ -37,6 +32,8 @@ the running containers.
                           status=(created|restarting|running|paused|exited)
                           name=<string> - container's name
                           id=<ID> - container's ID
+                          before=(<container-name>|<container-id>)
+                          since=(<container-name>|<container-id>)
                           ancestor=(<image-name>[:tag]|<image-id>|<image@digest>) - filters containers that were
                           created from the given image or a descendant.
 
@@ -58,10 +55,10 @@ the running containers.
   Print usage statement
 
 **-l**, **--latest**=*true*|*false*
-   Show only the latest created container, include non-running ones. The default is *false*.
+   Show only the latest created container (includes all states). The default is *false*.
 
 **-n**=*-1*
-   Show n last created containers, include non-running ones.
+   Show n last created containers (includes all states).
 
 **--no-trunc**=*true*|*false*
    Don't truncate output. The default is *false*.
@@ -72,9 +69,6 @@ the running containers.
 **-s**, **--size**=*true*|*false*
    Display total file sizes. The default is *false*.
 
-**--since**=""
-   Show only containers created since Id or Name, include non-running ones.
-
 # EXAMPLES
 # Display all containers, including non-running