bugfindutils - Bugs: bug #29698, Correct and clarify documentation...

 
 

bug #29698: Correct and clarify documentation of xargs -d option

Submitted by:  Jon Jensen <jonjensen>
Submitted on:  Wed 28 Apr 2010 04:04:59 AM UTC  
 
Category: documentationSeverity: 3 - Normal
Item Group: NoneStatus: Fixed
Privacy: PublicAssigned to: James Youngman <jay>
Originator Name: Open/Closed: Closed
Release: NoneFixed Release: 4.5.11

Add a New Comment (Rich MarkupRich Markup):
   

You are not logged in

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

 

Sun 15 May 2011 05:43:27 PM UTC, comment #4:

I've updated the manpage like this:

Input items are terminated by the specified character. The
specified delimiter may be a single character, a C-style charac‐
ter escape such as \n, or an octal or hexadecimal escape code.
Octal and hexadecimal escape codes are understood as for the
printf command. Multibyte characters are not supported. When
processing the input, quotes and backslash are not special; ev‐
ery character in the input is taken literally. The -d option
disables any end-of-file string, which is treated like any other
argument. You can use this option when the input consists of
simply newline-separated items, although it is almost always
better to design your program to use --null where this is possi‐
ble.

James Youngman <jay>
Project AdministratorIn charge of this item.
Tue 17 Aug 2010 04:17:30 PM UTC, comment #3:

I see what you're saying now about the input vs. the -d argument. The way the help reads, I thought it was saying there's nothing special about a backslash in the -d argument, which isn't true, because of C backslash escapes.

So I don't think the help is wrong, but it was unclear to me. I would find it clearer if it were reordered to group all notes about the specified character together, followed by all notes about the input text, followed by other notes.

Input items are terminated by the specified character. The specified delimiter may be a single character, a C-style character escape such as \n, or an octal or hexadecimal escape code. Multibyte characters are not supported. Any extra characters beyond the first one are ignored. Note that you likely need to quote backslashes for your shell, for example \n as '\n'.

Every character in the input is taken literally; quotes and backslash are not special there.

Disables the end-of-file string, which is treated like any other argument. This can be used when the input consists of simply newline-separated items, although it is almost always better to design your program to use --null where this is possible.

Jon Jensen <jonjensen>
Sun 15 Aug 2010 11:57:35 AM UTC, comment #2:

(if no response within a couple of weeks, I'll close this bug)

James Youngman <jay>
Project AdministratorIn charge of this item.
Fri 30 Apr 2010 07:47:45 AM UTC, comment #1:

But quotes are special:

~$ cat sample.txt
"hello world" foo bar
~$ xargs -n1 echo arg < sample.txt
arg hello world
arg foo
arg bar

I'm not sure I understand what you are trying to say about backslashes and the shell.

If you are talking about backslashes in the input, they are not special, as specified by this text:
<<
-d delim
Input items are terminated by the specified character. Quotes and backslash are not special; every character in the input is taken literally.

>>


If you are talking about backslashes within delim, then this is specified by this text:
<<
The specified delimiter may be a single character, a C-style character escape such as \n, or an octal or hexadecimal escape code. Octal and hexadecimal escape codes are understood as for the printf command.

>>

James Youngman <jay>
Project AdministratorIn charge of this item.
Wed 28 Apr 2010 04:04:59 AM UTC, original submission:

This documentation patch is to clarify xargs -d. HTH.

http://github.com/jonjensen/findutils/commit/da2a78ce9d75354639bfc706bc9d5b96850f43c3

Backslash is special to -d, as was explained later in the paragraph.

Quotes are not special, but I'm not sure who would think they are, and stating that they're not invites confusion as it implies shell quoting may not apply.

Give an example of shell quoting.

Note that any extra characters beyond the first one are ignored.

Jon Jensen <jonjensen>

 

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

Attach File(s):
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -unavailable- added by jay (Posted a comment)
  • -unavailable- added by jonjensen (Submitted the item)
  •  

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

    Only logged-in users can vote.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

     

     

    Follow 6 latest changes.

    Date Changed By Updated Field Previous Value => Replaced By
    Sat 02 Feb 2013 02:55:06 PM UTCjayOpen/ClosedOpen=>Closed
      Fixed ReleaseNone=>4.5.11
    Sun 15 May 2011 05:43:27 PM UTCjayStatusNone=>Fixed
    Wed 11 May 2011 09:44:14 AM UTCjayStatusNeed Info=>None
    Fri 30 Apr 2010 07:47:45 AM UTCjayStatusNone=>Need Info
      Assigned toNone=>jay

    Back to the top


    Powered by Savane 3.1-cleanup