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

 
 

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

Submitter:  Jon Jensen <jonjensen>
Submitted:  Wed 28 Apr 2010 04:04:59 AM UTC
   
 
Category:  documentation Severity:  3 - Normal
Item Group:  None Status:  Fixed
Privacy:  Public Assigned to:  jay
Originator Name:  Open/Closed:  Closed
Release:  None Fixed Release:  4.5.11
* Mandatory Fields

Add a New Comment Rich Markup
   

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>
Group administrator
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>
Group administrator
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>
Group administrator
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 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 jay (Posted a comment)
  • -email is unavailable- added by jonjensen (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.

     

    Follow 6 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2013-02-02 jay Open/ClosedOpen Closed
        Fixed ReleaseNone 4.5.11
    2011-05-15 jay StatusNone Fixed
    2011-05-11 jay StatusNeed Info None
    2010-04-30 jay StatusNone Need Info
        Assigned toNone jay

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code