Fix ./pants help docs on command line specs (Cherry-pick of #16616) (…

…#16624)

This needed to be updated for the specs redesign project from Pants 2.13.

[ci skip-rust]
[ci skip-build-wheels]

docs/markdown/Using Pants/command-line-help.md

@@ -10,13 +10,11 @@ Run `./pants help` to get basic help, including a list of commands you can run t
 
 ```text Shell
 ❯ ./pants help
-
-
 Pants 2.14.0
 
 Usage:
 
-  ./pants [options] [goals] [files/targets]  Attempt the specified goals on the specified files/targets.
+  ./pants [options] [goals] [inputs]          Attempt the specified goals on the specified inputs.
   ./pants help                               Display this usage message.
   ./pants help goals                         List all installed goals.
   ./pants help targets                       List all installed target types.
@@ -29,15 +27,13 @@ Usage:
   ./pants help-advanced [goal/subsystem]     Help for a goal or subsystem's advanced options.
   ./pants help-all                           Print a JSON object containing all help info.
 
-  [file] can be:
-     path/to/file.ext
-     A path glob, such as '**/*.ext', in quotes to prevent premature shell expansion.
-
-  [target] can be:
-    path/to/dir:target_name.
-    path/to/dir for a target whose name is the same as the directory name.
-    path/to/dir:  to include all targets in the specified directory.
-    path/to/dir:: to include all targets found recursively under the directory.
+  [inputs] can be:
+     A file, e.g. path/to/file.ext
+     A path glob, e.g. '**/*.ext' (in quotes to prevent premature shell expansion)
+     A directory, e.g. path/to/dir
+     A directory ending in `::` to include all subdirectories, e.g. path/to/dir::
+     A target address, e.g. path/to/dir:target_name.
+     Any of the above with a `-` prefix to ignore the value, e.g. -path/to/ignore_me::
 
 Documentation at https://www.pantsbuild.org
 Download at https://pypi.org/pypi/pantsbuild.pants/2.14.0

src/python/pants/help/help_printer.py

@@ -334,8 +334,8 @@ def print_cmd(args: str, desc: str):
         print(f"\nPants {pants_version()}")
         print("\nUsage:\n")
         print_cmd(
-            "[options] [goals] [files/targets]",
-            "Attempt the specified goals on the specified files/targets.",
+            "[options] [goals] [inputs]",
+            "Attempt the specified goals on the specified inputs.",
         )
         print_cmd("help", "Display this usage message.")
         print_cmd("help goals", "List all installed goals.")
@@ -355,24 +355,20 @@ def print_cmd(args: str, desc: str):
         print_cmd("help-all", "Print a JSON object containing all help info.")
 
         print("")
-        print("  [file] can be:")
-        print(f"     {self.maybe_cyan('path/to/file.ext')}")
+        print("  [inputs] can be:")
+        print(f"     A file, e.g. {self.maybe_cyan('path/to/file.ext')}")
         glob_str = self.maybe_cyan("'**/*.ext'")
+        print(f"     A path glob, e.g. {glob_str} (in quotes to prevent premature shell expansion)")
+        print(f"     A directory, e.g. {self.maybe_cyan('path/to/dir')}")
         print(
-            f"     A path glob, such as {glob_str}, in quotes to prevent premature shell expansion."
+            f"     A directory ending in `::` to include all subdirectories, e.g. {self.maybe_cyan('path/to/dir::')}"
         )
-        print("\n  [target] can be:")
-        print(f"    {self.maybe_cyan('path/to/dir:target_name')}.")
+        print(f"     A target address, e.g. {self.maybe_cyan('path/to/dir:target_name')}.")
         print(
-            f"    {self.maybe_cyan('path/to/dir')} for a target whose name is the same as the directory name."
+            f"     Any of the above with a `-` prefix to ignore the value, e.g. {self.maybe_cyan('-path/to/ignore_me::')}"
         )
-        print(
-            f"    {self.maybe_cyan('path/to/dir:')}  to include all targets in the specified directory."
-        )
-        print(
-            f"    {self.maybe_cyan('path/to/dir::')} to include all targets found recursively under the directory.\n"
-        )
-        print(f"Documentation at {self.maybe_magenta('https://www.pantsbuild.org')}")
+
+        print(f"\nDocumentation at {self.maybe_magenta('https://www.pantsbuild.org')}")
         pypi_url = f"https://pypi.org/pypi/pantsbuild.pants/{pants_version()}"
         print(f"Download at {self.maybe_magenta(pypi_url)}")