Wrong documentation for 'od'

[Zakhar]

Binary package hint: coreutils

The documentation from

od --help

and from

man od

diverge on the short name for the --string option.

od --help says:
  -s, --strings[=BYTES]
(note the lowercase -s)

man od says:
 -S, --strings[=BYTES]
(note now it is uppercase -S)

The right documentation for this option is the one in the 'man', because the desired featured is indeed achieved through -S (uppercase).

Thus od --help displays wrong informations and should be corrected.

(Probably upstream ?)

I discovered that trying to port a script I wrote for Lucid to a BusyBox running on a NAS.
Unfortunately the guys at BusyBox programmed as it is documented in the --help, and thus BusyBox's od and GNU's od have diverging features.

... nasty trick GNU guys have plaid to BusyBox, and they should probably be warned (if they don't already know because I have to cope with an old BusyBox).

[C de-Avillez (hggdh2)]

Thank you for opening this bug and helping make Ubuntu better. Unfortunately you did not specify what version of Ubuntu (and of coreutils) you are using, which makes it a bit more difficult to pinpoint your issue.

Nevertheless, I went ahead and checked Lucid (since, in your description, you refer to Lucid):

ubuntu@cempedak:~$ lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description: Ubuntu 10.04.2 LTS
Release: 10.04
Codename: lucid
ubuntu@cempedak:~$ od --version
od (GNU coreutils) 7.4
Copyright (C) 2009 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Written by Jim Meyering.
ubuntu@cempedak:~$ od --help | grep strings
  -S, --strings[=BYTES] output strings of at least BYTES graphic chars
ubuntu@cempedak:~$

From 'man od' I see:

       -S, --strings[=BYTES]
              output strings of at least BYTES graphic chars

So, at least on Lucid, this is not an issue. So, without more details from you, I do not see this issue.

Also, the full documentation for any coreutils utility is provided as an 'info' page; '--help' and 'man' are summarised (in fact, the 'man' entries are generated _from_ the ' --help').

Finally, I fail to see why this would be a trick -- even more a nasty one -- played by upstream coreutils on any one. Bugs happen.

Marking Incomplete/Low

[Zakhar (alainb06)]

Sorry for the lack of precision, and you got it right, I'm on Lucid.

Here are the details :

$ lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description: Ubuntu 10.04.2 LTS
Release: 10.04
Codename: lucid

$ which od
/usr/bin/od

$ od --version
od (GNU coreutils) 7.4
Copyright © 2009 Free Software Foundation, Inc.
License GPLv3+ : GNU GPL version 3 ou ultérieure
<http://gnu.org/licenses/gpl.html>
Ceci est logiciel libre, vous êtes libre de le modifier et de le redistribuer.
Ce logiciel n'est accompagné d'ABSOLUMENT AUCUNE GARANTIE, dans les limites
autorisees par la loi applicable.

Écrit par Jim Meyering.

$ apt-file find /usr/bin/od | grep '/usr/bin/od$'
coreutils: /usr/bin/od

$ dpkg-query -p coreutils
Package: coreutils
Essential: yes
Priority: required
Section: utils
Installed-Size: 12988
Maintainer: Ubuntu Developers <email address hidden>
Architecture: amd64
Version: 7.4-2ubuntu3
Replaces: mktemp
Pre-Depends: libacl1 (>= 2.2.11-1), libattr1 (>= 2.4.41-1), libc6 (>= 2.11), libselinux1 (>= 1.32)
Filename: pool/main/c/coreutils/coreutils_7.4-2ubuntu2_amd64.deb
Size: 2907398
MD5sum: 470929f93d3c47fd45d82f96880e6637
Description: The GNU core utilities
 This package contains the essential basic system utilities.
 .
 Specifically, this package includes:
 basename cat chgrp chmod chown chroot cksum comm cp csplit cut date dd df dir
 dircolors dirname du echo env expand expr factor false fmt fold groups head
 hostid id install join link ln logname ls md5sum mkdir mkfifo mknod mktemp
 mv nice nl nohup od paste pathchk pinky pr printenv printf ptx pwd readlink
 rm rmdir sha1sum seq shred sleep sort split stat stty sum sync tac tail tee
 test touch tr true tsort tty uname unexpand uniq unlink users vdir wc who
 whoami yes
Original-Maintainer: Michael Stone <email address hidden>

The man is correct.

But on my installation I got:

$ od --help | grep strings
  -s, --strings[=BYTES] affiche les chaînes d'au moins BYTES caractères

And it is INDEED a lowercase 's' letter.

So if you got eitherwise... could it be a "translation" bug?
Maybe it is only the "French version" of the help that is wrong, because afterall, as you can see, the rest of the sentence after -s, --strings[=BYTES] has been translated to French.

P.S.: of course I was joking about the bug and bad trick for Busybox. I do agree with you bug happens, and in the Free/Open Source people don't do this sort of trick on purpose.
I can also ensure you that the Busybox I tested (running on a Synology 1010) do only accept -s (lowercase) for strings, and complains with -S
So I can only assume that this bug is not only on my PC!.. But after all, it might be already fixed.

[Zakhar (alainb06)]

More info (could confirm a translation bug)

od --help

=> French output, says -s = INCORRECT

man od

=> Untranslated (English) output, says -S = CORRECT

info od

=> Untranslated (English) output, says -S = CORRECT

[C de-Avillez (hggdh2)]

Yes, it does sound like a translation issue... I will install the French language pack on one of my servers (currently on Lucid), and test on my laptop (running Natty) under fr.FR (which I am assuming is your language.

[C de-Avillez (hggdh2)]

Yes indeed, translation issue. I did not even need to test on Lucid, my laptop shows it as well:

[cerdea-aws]$ env LANGUAGE=fr_FR:fr od --help | grep strings
  -s, --strings[=BYTES] affiche les chaînes d'au moins BYTES caractères
[cerdea-aws]$ env LANGUAGE=fr_FR:fr od --version
od (GNU coreutils) 8.5
Copyright © 2010 Free Software Foundation, Inc.
License GPLv3+ : GNU GPL version 3 ou ultérieure
<http://gnu.org/licenses/gpl.html>
Ceci est logiciel libre, vous êtes libre de le modifier et de le redistribuer.
Ce logiciel n'est accompagné d'ABSOLUMENT AUCUNE GARANTIE, dans les limites
autorisees par la loi applicable.

Écrit par Jim Meyering.
[cerdea-aws]$

[Zakhar (alainb06)]

Nice you could track it down so quickly!..

I can see it is still in the recent versions (coreutils 8.5)

And yes indeed, I'm on fr_FR (or seems so, I don't have a LANGUAGE variable in env, but only LANG saying fr_FR)

$ env | grep -i lang
LANG=fr_FR.UTF-8
GDM_LANG=fr_FR.UTF-8

And just to be sure, if I do the opposite of your test above

$ env LANGUAGE=en_GB:en od --help | grep strings
  -S, --strings[=BYTES] output strings of at least BYTES graphic chars

... it becomes right!

[C de-Avillez (hggdh2)]

Marking Triaged for Coreutils, opening a task for the Ubuntu Translations project.

[C de-Avillez (hggdh2)]

@Zakhar: My pleasure :-)

I see the translation team has already assigned their task to the FR translators. One thing left is this might be a good candidate for a Lucid SRU; right now it would be fixed for Oneiric (the current in-development version) only.

Also, please do not hesitate in opening a new bug on problems you find.

[Zakhar (alainb06)]

@C de-Avillez: Thanks :-)

And I won't hesitate to report other problems, it is my very modest contribution to improvement The Free Software!

.

For the record, I did also report the issue to Busybox guys as a "non-compliance"

https://bugs.busybox.net/show_bug.cgi?id=3769

Because in the Busybox documentation, we can see that they aim to be as compliant as possible to GNU behavior for the small tools they have around the tiny kernel.
Obviously, their 'od' relying on the -s option short for --string is not-compliant

... or at best is compliant with the French translation bug in 'od'... which is certainly not what they intended :/

For the correction of this bug on Lucid, rest assure, it doesn't disturb me a lot as it is really minor for the GNU version of 'od' as it is only a documentation typo.

For Busybox it is minor but more annoying because it disrupts scripts relying on the short option -S of 'od' (that's what happens to my script), although it can be workarounded easily using long options.

What happens to the 'od' in Busybox makes me think that this typo on the --help could have existed in English (in the past) and if so, could still be in other languages. If translators have some time to check, it could be a good idea to do so (I have only English & French on my system)

[C de-Avillez (hggdh2)]

Upstream has been faster on the uptake than I was. I had just tested coreutils GIT, and found the same issue, and was preparing an email to bugs-coreutils (and finding who are the translators for French). I should have done that already... instead I initially thought it was an Ubuntu translation issue. Ah well.

But Jim checked, and found that 12 locales are affected by this; he additionally found some other changes needed in a few locales. I am adding a link to his email.

[C de-Avillez (hggdh2)]

Duh. It works better if I actually link Jim's email.

http://lists.gnu.org/archive/html/coreutils/2011-05/msg00076.html

[Jim Meyering (meyering)]

C de-Avillez wrote:
> Upstream has been faster on the uptake than I was. I had just tested
> coreutils GIT, and found the same issue, and was preparing an email to
> bugs-coreutils (and finding who are the translators for French). I
> should have done that already... instead I initially thought it was an
> Ubuntu translation issue. Ah well.
>
> But Jim checked, and found that 12 locales are affected by this; he
> additionally found some other changes needed in a few locales. I am
> adding a link to his email.

Oh, sorry I didn't Cc this bug.

[Zakhar (alainb06)]

Very impressive how quick you all are !..

@Jim, I don't know how to reply on the upstream mailing list, but I assume it's safe if you make the minimal fix as suggested because the typo is just on the name of the short option. So it's something like replacing '-s, --strings[=BYTES]' by '-S, --strings[=BYTES]', the text after that is correct, at least in French (and spanish that I can understand).

For the other modifications there could be more risk as they seem to be somewhere in the middle of the translated piece, but still looks safe to translate (I can't imagine a language where '-t d2' is a real word, unless you speak SMS... or Klingon may be -Klingon in the list of languages always makes me laugh- :-P )

.

Some new from the guys at Busybox: no harm done, they have corrected the text of the od --help in version 1.3.0 which was... 4 and a half years ago. I must have got a very very old version of Busybox's od to still get such an old typo!

[Stéphane Raimbault (sra)]

As stated on the coreutils mailing list, the best way to proceed is to contact the translation maintainers or you won't be immune to a regression when the maintainer will push a update w/o the fix because there is version control system for the translations of coreutils.

I've updated the French translation of coreutils (from 8.9 to 8.12) in upstream (Jim have contacted the French translation project).

Thank you for the report.

[Zakhar (alainb06)]

Hello, I don't know about this new status... I reported this bug at the time of Lucid, now in Precise, we have version 8.13 of coreutils as apt-get shows

$ apt-cache show coreutils
Package: coreutils
Essential: yes
Priority: required
Section: utils
Installed-Size: 5496
Maintainer: Ubuntu Developers <email address hidden>
Original-Maintainer: Michael Stone <email address hidden>
Architecture: amd64
Version: 8.13-3ubuntu3.1
Replaces: mktemp, timeout
Depends: dpkg (>= 1.15.4) | install-info
Pre-Depends: libacl1 (>= 2.2.51-5), libattr1 (>= 1:2.4.46-5), libc6 (>= 2.15), libselinux1 (>= 1.32)
Conflicts: timeout
Filename: pool/main/c/coreutils/coreutils_8.13-3ubuntu3.1_amd64.deb

In this version 8.13 I can confirm that the documentation bug (in fact translation bug) is fixed for me.

I had an exchange with the maintainer by e-mail, and this translation bug was affecting also other languages. I can confirm only for French though.

So I'll stop watching this bug as for me it has status:

==> fixed

[Zakhar (alainb06)]

And on second thoughts, this bug was posted for Lucid (10.04).

Lucid is using version 7.4 of coreutils:
$ apt-cache show coreutils
Package: coreutils
Essential: yes
Priority: required
Section: utils
Installed-Size: 12988
Maintainer: Ubuntu Developers <email address hidden>
Original-Maintainer: Michael Stone <email address hidden>
Architecture: amd64
Version: 7.4-2ubuntu3

Lucid is still maintained, and the documentation bug is still there (for French translation and other languages)... and I doubt upstream will fix a translation bug on the help for this very old coreutils version.

Indeed it is not so important as the correct documentation can be found
- in english (it's OK, only some languages got bugs in the translation)
- in the man (it is correct... as it is in English even for French versions of Ubuntu!)
- searching on the web.

It does not prevent od from working correctly.

So indeed, for Lucid, where the bug is still present:

Importance ==> Low
seams fine.

... but

Status ==> Invalid
is strange, as I confirm the bug is still there!
Of course if you want to reproduce the bug you must have the buggy translations installed on your system (take French for example), and issue the command after having set the LANG variable to some variant of French.