sed -i option needs clarification in manpage

[BigBoy_PDB]

What the sed -i[SUFFIX] does (specifically, the fact that it appends the suffix to the backup's filename) is ambiguous.

[Mackenzie Morgan (maco.m)]

Not a bug, user error. See the manpage. It says -i[suffix]. By putting -ir you are telling it to put an r at the end of the file name. The correct syntax to use is -i -r

[BigBoy_PDB (bigboy-pdb)]

Thank you for your response. You're right.

The man page is ambiguous with respect to the the addition of a suffix. How could I edit or report a change to a man page?

A statement along the lines of:

"sed -iSuffix Pattern File"
is equivalent to the command
"cp File FileSuffix; sed -i Pattern File"

or

When SUFFIX is provided, a copy of the original file is created which has SUFFIX appended to the end of the file name.

would make the use of -i[SUFFIX] clearer.

Thank you again (and sorry for filing a false bug report),
Dave

--- On Thu, 9/18/08, Mackenzie Morgan <email address hidden> wrote:
From: Mackenzie Morgan <email address hidden>
Subject: [Bug 271606] Re: In sed, -ir options generate second file with r appended to end of name
To: <email address hidden>
Received: Thursday, September 18, 2008, 1:10 AM

Not a bug, user error. See the manpage. It says -i[suffix]. By
putting -ir you are telling it to put an r at the end of the file name.
The correct syntax to use is -i -r

** Changed in: sed (Ubuntu)
       Status: New => Invalid

--
In sed, -ir options generate second file with r appended to end of name
https://bugs.launchpad.net/bugs/271606
You received this bug notification because you are a direct subscriber
of the bug.

      __________________________________________________________________
Instant Messaging, free SMS, sharing photos and more... Try the new Yahoo! Canada Messenger at http://ca.beta.messenger.yahoo.com/

[Mackenzie Morgan (maco.m)]

So, what it actually says is:
-i[SUFFIX], --in-place[=SUFFIX]

              edit files in place (makes backup if extension supplied)

For someone new to manpages it might be a bit ambiguous, but man man states that [] mean it's optional, and the comment underneath the -i[SUFFIX] line does make it clear that adding a suffix will back it up. I suppose the unclear part is exactly what the backup will be named. That sort or requires extrapolating from the whole "why am i giving a suffix?" thing.

I'm going to mark this a string-fix and bitesize bug since changing a manpage string is simple enough.

[Jonathan Marsden (jmarsden)]

Many GNU utilities have more detailed info documentation than man pages. The See Also section of the sed man page is very clear about this.

  info sed Invoking

provides more information about the use of the sed options, including -i and that suffix. This information includes substitution for * , and so forth, which is not addressed at all by the suggested statements to "improve" the man page in this bug report.

If it is really felt to be necessary to add this information to the man page (as well as the info database, where the information already exists and which is already pointed to by the man page) please do be sure to add correct information to the man page!

My instinct is that anyone using sed deeply enough to use the -i[SUFFIX] option will be (or should be) using info sed rather than man sed to read the detailed sed documentation anyway :)

[Mackenzie Morgan (maco.m)]

I think the issue is just that when looking at the manpage, the meaning of "-
i[SUFFIX]" is unclear, particularly what "[SUFFIX]" means. Normally, multiple
arguments that use a single - can be used together, so the fact that sed
doesn't allow that in the -ir case (but does in the -ri case) is inconsistent
and should have attention brought to it.

[Jonathan Marsden (jmarsden)]

> "Normally, multiple arguments that use a single - can be used together..."

Only if you happen to define "normally" as "those switches which do not have arguments". This is just the way option switches with arguments work. And have worked for many years.

This is not specific to sed. Perl has a similar -i option, its man page does not go out of its way to remind people that switches which take arguments can't be combined like that (example: perl -pie "s/a/b/" somefile.txt does not do what you seem to think is "normal"). cp does not point this out for the -S switch in its man page, for another example (example: touch junk junk2 ; cp -bSp junk junk2 does not do what you think is "normal" either). These are very common, very well known programs. Perhaps more commonly used that sed!

It seems peculiar to me to to ask that the sed man page should be "fixed" to "have attention brought to" this behaviour, without being consistent, and requiring this change for all affected man pages. This behaviour is not at all sed-specific, it is simply the way getopt parsing works when single character switches have arguments.

On that basis, I do not see how this (the omission of general info about how single character switches with arguments cannot be combined except as the last switch in such a combination) can really be considered a bug in the sed man page.

As I see it, either:

  (a) this is the expected behaviour of getopt for switches with arguments, and so is not a bug, or
  (b) this is unexpected behaviour, so getopt should not allow such option switches at all, or
  (c) this is unexpected behaviour, but is useful, so every single man page where such a switch is used needs to be sure to "bring attention to" this.

Of those possibilities, I'll vote for (a) :)

[Evan R. Murphy (evanrmurphy)]

Presuming there is more or less consensus on Jonathan Marsden's (a), I'm setting the status of this bug report to Invalid. If there are objections, speak up and revert the status!