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

Submitted by:  None
Submitted on:  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

Add a New Comment(Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

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>
Project 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 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:

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>
Project 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)
  •  

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.

     

     

     

    No changes have been made to this item

    Back to the top


    Powered by Savane 3.4