docs: mention that when piping xargs may end up invoking Pants goal more than once (#20521)

Documenting the implications of using `xargs` when producing structured
data out of Pants goals, see
#20462 for context.

---------

Co-authored-by: Andreas Stenius <[email protected]>

Author: AlexTereshenkov

docs/docs/using-pants/advanced-target-selection.mdx

@@ -145,7 +145,7 @@ Whereas `tags` are useful for _decentralized_ allow/block lists, `--spec-files`
 To pipe a Pants run, use your shell's `|` pipe operator and `xargs`:
 
 ```bash
-pants dependents helloworld/util | xargs pants  list
+pants dependents helloworld/util | xargs pants list
 ```
 
 You can, of course, pipe multiple times:
@@ -167,6 +167,14 @@ $ pants dependencies helloworld/util > util_dependencies.txt
 $ pants --spec-files=util_dependencies.txt lint
 ```
 
+Using spec files is also more robust because when piping output of a Pants goal to `xargs`, the specified command
+may be invoked by `xargs` as many times as necessary to use up the list of input items.
+This may break the structured data output, for instance, when you want to `peek` the targets as JSON:
+
+```bash
+$ pants list --filter-target-type=resource :: | xargs pants peek
+```
+
 If you don't want to save the output to an actual file—such as to not pollute version control—you can use a variable and a named pipe:
 
 ```bash

docs/docs/using-pants/project-introspection.mdx

@@ -250,6 +250,10 @@ pants dependents  helloworld/main.py:lib | xargs pants peek --exclude-defaults
 ]
 ```
 
+Keep in mind, however, that the `peek` goal may be invoked by `xargs` as many times as necessary to use up the list
+of input items. This may break the structured data output, so it may be safer to use the
+[`--spec-files`](../../reference/global-options#spec_files) option.
+
 :::
 
 ## `paths` - find dependency paths