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

[Vladimir Nikishkin]

Follow-up Comment #2, bug #55190 (project findutils):

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. 



    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?55190>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/