bugfindutils - Bugs: bug #55190, xargs documentation is confusing...

 
 

bug #55190: xargs documentation is confusing about the usage of -i and -I (capital i), and doesn't have any examples on this options

Submitter:  None
Submitted:  Mon 10 Dec 2018 03:47:22 AM UTC
   
 
Category:  xargs Severity:  3 - Normal
Item Group:  None Status:  None
Privacy:  Public Assigned to:  None
Originator Name:  lockywolf Originator Email:  -email is unavailable-
Open/Closed:  Open Release:  4.6.0
Fixed Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Wed 12 Dec 2018 12:00:54 AM UTC, comment #3: 

Actually POSIX is what the GNU findutils basically follow ... with
the exception of additional GNU goodies ;-)

GNU standards say that "man pages are secondary" [1], and
that the primary documentation should be available as Texinfo manual.
Some GNU packages like the coreutils therefore generate the man
pages from --help output (with some amendments).
The findutils still have a lot of information in both formats
(man + texinfo).  My personal opinion is that maintaining both
formats requires quite some resources, and yield both redundancy
and (sometimes) the risk of discrepancies.
For now, I wouldn't necessarily want to change that, but I could
imagine that we could merge the most useful stuff together in the
Texinfo format one day, and generate the man pages from --help,
like others.  Obviously, this is an awful step for the translators.

[1] https://www.gnu.org/prep/standards/html_node/Man-Pages.html

Re. the actual case: suggestions/patches are welcome, in small
pieces to improve the documentation step by step.

Have a nice day,
Berny

Bernhard Voelker <berny>
Group administrator
Tue 11 Dec 2018 04:40:01 AM UTC, comment #2: 

1)Well, for me, as another non-English-native speaker, there is :). For me, the wording here seems really confusing. I think that in the posix 1p man the explanation is more understandable, but that's my personal preference.

( I hope I'm not tainting Savannah by copying from there. :))

https://pubs.opengroup.org/onlinepubs/9699919799/utilities/xargs.html


-I  replstr
    [XSI] [Option Start] Insert mode: utility is executed for each logical line from standard input. Arguments in the standard input shall be separated only by unescaped <newline> characters, not by <blank> characters. Any unquoted unescaped <blank> characters at the beginning of each line shall be ignored. The resulting argument shall be inserted in arguments in place of each occurrence of replstr. At least five arguments in arguments can each contain one or more instances of replstr. Each of these constructed arguments cannot grow larger than an implementation-defined limit greater than or equal to 255 bytes. Option -x shall be forced on. [Option End]


I also think that something like the following sidenote should be added:

"(NB: A commonly used value for replstr is '{}', as this string is also used by `find' to mean substitution.

1.1)Yes, I know.
I deliberately crafted a confusing example, as such examples are likely to be produced by newbies, and are likely entry points.

2) Hmm...
Well, I usually interpret the documentation paradigm like this:
man commandname is for a brief description of what it does, and a cookbook for the impatient and script-kiddies. (Well, actually for people who are likely to only use a command once in their life.)
info commandname is for those who really need some understanding how this thing really works.

If GNU agrees with this usage protocol, maybe I can try and craft some more cookbook examples and send a patch.
If GNU instead want to popularize info by creating additional incentives in the shape of a bigger number of examples provided in `info', but not man, I would suggest to add one or more lines to the manpage urging the user to refer to the info node.


Vladimir Nikishkin <lockywolf>
Mon 10 Dec 2018 02:28:00 PM UTC, comment #1: 

1)
Regarding the terms "replace" vs. "substitute": for me as non-English-native speaker,
there's no difference between 'replace' and 'substitute.

Your example can be simplified by avoiding the files AAA.txt and BBB.txt:
it simply reads:

  $ echo line | xargs -I {} echo line2

As documented both in the man page and the Texinfo manual - and even in "xargs --help",
the -I option works on the "initial arguments".  Looking at the synopsis clarifies:


Usage: xargs/xargs [OPTION]... COMMAND [INITIAL-ARGS]...
...
  -I R                         same as --replace=R
  -i, --replace[=R]            replace R in INITIAL-ARGS with names read
                                 from standard input; if R is unspecified,
                                 assume {}


In your example above, the initial args is the string "line2". So there xargs
cannot replace '{}' because there is none.

2) findutils' info pages has a separate node to explain -I,-e,--replace incl. examples:

https://www.gnu.org/software/findutils/manual/html_node/find_html/Interspersing-File-Names.html#Interspersing-File-Names

With the above, do you see things in the documentation which could
be improved?  Concrete suggestions and patches welcome. ;-)

Have a nice day,
Berny

Bernhard Voelker <berny>
Group administrator
Mon 10 Dec 2018 03:47:22 AM UTC, original submission:  

These are actually two different questions, but I find them often found together.

1)-I option is called 'replace-str', which to me is particularly confusing, because by 'replace' I usually mean some sort of post-processing of my data. The wording convenient to me (and I suspect, to many other people) would be 'substitute'.

Initially, I understood this option as if it replaces the input to xargs with itself. That is, for the command:

AAA.txt:
line

BBB.txt:
line2

cat AAA.txt |  xargs -I {} echo `cat BBB.txt'

I expected the final commannd to be

echo {}2

But the actual command is:

echo line2 line

2)There are no examples in the info xargs which could debunk my misunderstanding.


Anonymous

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by lockywolf (Posted a comment)
  • -email is unavailable- added by berny (Posted a comment)
  • -email is unavailable- added by None (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    No changes have been made to this item

    Back to the top

    Powered by Savane 3.13-758e.
    Corresponding source code