On 4/21/23 01:20, Dan Jacobson wrote:
If we read (info "(coreutils) cat invocation") we also get told about (info "(coreutils) Common options")But if we read e.g., (info "(find) Invoking xargs") we never know about (info "(coreutils) Common options") even though they also apply. So unlike cat, for xargs, even if the user has exhausted all the documentation steps, man, --help, INFO, he will never learn about "--". Sure, (info "(coreutils) Common options") says "In fact, every GNU program accepts ... these options."
The ellipsis "..." stands for "(or should)" in the original coreutils Texinfo manual. It's not a must to accept "--". E.g. while find(1) accepts it, the double dash "--" is not really useful due to the way the tool is expected to parse its arguments. The man page of find(1) describes it: A double dash -- could theoretically be used to signal that any remaining arguments are not options, but this does not really work due to the way find determines the end of the following path arguments: it does that by reading until an expression argument comes (which also starts with a `-'). Now, if a path argument would start with a `-', then find would treat it as expression argument instead. [...]
That's great, but some don't directly or indirectly document that fact.
An true, the man page of xargs(1) didn't describe "--" until now. Done with the attached, and pushed at: https://git.savannah.gnu.org/cgit/findutils.git/commit/?id=bbd06d8e065 Thanks for the report. Have a nice day, Berny
From bbd06d8e0651cffe632df1e3eaf97b47ecc4e5dd Mon Sep 17 00:00:00 2001 From: Bernhard Voelker <m...@bernhard-voelker.de> Date: Tue, 23 May 2023 21:52:42 +0200 Subject: [PATCH] doc: document double dash "--" option delimiter for xargs * doc/find.texi (node xargs options): Add description of the "--" option delimiter. * xargs/xargs.1 (OPTIONS): Likewise. * NEWS (Documentation Changes): Document the change. Suggested by Dan Jacobson <jida...@jidanni.org> in <https://lists.gnu.org/r/bug-findutils/2023-04/msg00009.html> --- NEWS | 2 ++ doc/find.texi | 8 ++++++++ xargs/xargs.1 | 16 ++++++++++++++++ 3 files changed, 26 insertions(+) diff --git a/NEWS b/NEWS index db232f41..476753f5 100644 --- a/NEWS +++ b/NEWS @@ -28,6 +28,8 @@ GNU findutils NEWS - User visible changes. -*- outline -*- (allout) When generating the Texinfo manual, `makeinfo` is invoked with the --no-split option for all output formats now; this avoids files like find.info-[12]. + The xargs documentation now describes the double dash "--" option delimiter. + * Noteworthy changes in release 4.9.0 (2022-02-22) [stable] diff --git a/doc/find.texi b/doc/find.texi index c3061665..0c837c2e 100644 --- a/doc/find.texi +++ b/doc/find.texi @@ -3868,6 +3868,14 @@ a program died due to a fatal signal. @subsection xargs options @table @code +@item -- +@findex option delimiter, -- +Delimit the option list. Later arguments, if any, are treated as operands even +if they begin with @samp{-}. For example, @samp{xargs -- --help} runs the +command @samp{--help} (found in @env{PATH}) instead of printing the usage text, +and @samp{xargs -- --mycommand} runs the command @samp{--mycommand} instead of +rejecting this as unrecognized option. + @item --arg-file@r{=@var{inputfile}} @itemx -a @r{@var{inputfile}} Read names from the file @var{inputfile} instead of standard input. diff --git a/xargs/xargs.1 b/xargs/xargs.1 index de6fbc69..c5fd5dfa 100644 --- a/xargs/xargs.1 +++ b/xargs/xargs.1 @@ -279,6 +279,22 @@ Exit if the size (see the .B \-s option) is exceeded. .TP +.B "\-\-" +Delimit the option list. Later arguments, if any, are treated as operands even +if they begin with +.IR \- . +For example, +.B xargs \-\- \-\-help +runs the command +.I \-\-help +(found in +.IR PATH ) +instead of printing the usage text, and +.B xargs \-\- \-\-mycommand +runs the command +.I \-\-mycommand +instead of rejecting this as unrecognized option. +.TP .B "\-\-help" Print a summary of the options to .B xargs -- 2.40.1
