binhex documentation claims unknown bug

[davidwilemski]

BPO	29557
Nosy	@birkenfeld, @rhettinger, @ronaldoussoren, @ned-deily, @berkerpeksag, @serhiy-storchaka, @Mariatta, @davidwilemski
PRs	bpo-29557: Remove abiguous line in binhex docs #90 [3.5] bpo-29557: Remove ambiguous line in binhex docs (#90) #474 [3.6] bpo-29557: Remove ambiguous line in binhex docs (#90) #475

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2017-03-25.05:53:17.508>
created_at = <Date 2017-02-14.16:20:44.013>
labels = ['OS-mac', 'type-bug', '3.7', 'docs']
title = 'binhex documentation claims unknown bug'
updated_at = <Date 2017-03-25.05:53:17.507>
user = 'https://github.com/davidwilemski'

bugs.python.org fields:

activity = <Date 2017-03-25.05:53:17.507>
actor = 'serhiy.storchaka'
assignee = 'docs@python'
closed = True
closed_date = <Date 2017-03-25.05:53:17.508>
closer = 'serhiy.storchaka'
components = ['Documentation', 'macOS']
creation = <Date 2017-02-14.16:20:44.013>
creator = 'David Wilemski'
dependencies = []
files = []
hgrepos = []
issue_num = 29557
keywords = []
message_count = 10.0
messages = ['287781', '287801', '287819', '287828', '287860', '287861', '287868', '289003', '290287', '290288']
nosy_count = 9.0
nosy_names = ['georg.brandl', 'rhettinger', 'ronaldoussoren', 'ned.deily', 'docs@python', 'berker.peksag', 'serhiy.storchaka', 'Mariatta', 'David Wilemski']
pr_nums = ['90', '474', '475']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue29557'
versions = ['Python 3.5', 'Python 3.6', 'Python 3.7']

[davidwilemski]

The binhex documentation has a line in it that says "As of this writing, hexbin() appears to not work in all cases."

This is a bit ambiguous and there is no context for what the bug may be. It appears this line is from the first commit to the hexbin function's documentation in 1995 (https://hg.python.org/cpython/rev/3911d4a89ab0#l4.40) but the commit also has no information about what this bug may be. I also see no current open bugs for the binhex module that seem related.

In 2009, there was a patch for the hexbin function but I have no idea if this is the bug from the original documentation or if it was something else entirely: https://bugs.python.org/issue6369

Given this, I believe the line should be removed unless more details about the referenced buggy behavior can be found.

[berkerpeksag]

New changeset 6de2b78 by Berker Peksag in branch 'master':
bpo-29557: Remove ambiguous line in binhex docs (#90)
6de2b78

[serhiy-storchaka]

I think this should be read in the context of previous lines:

If you code or decode textfiles on non-Macintosh platforms they will still use
the old Macintosh newline convention (carriage-return as end of line).

And may be related to the in-code comment:

# XXXX Do translation on non-mac systems

[rhettinger]

Georg, do remember why this admonition was present?

[ronaldoussoren]

I think the comment about needing translation on non-mac systems is incorrect. Binhex is (or rather was) a textual encoding for binary files used on classic MacOS. The encoded file is more likely to be binary data than a text file and replacing b'\r' by the line ending of the current platform could well corrupt that data.

[serhiy-storchaka]

File flags are saved in binhex format, therefore it is possible to distinguish text files from binary files.

[birkenfeld]

I don't remember anything specific about this, sorry.

[serhiy-storchaka]

See also bpo-29566. Perhaps hexbin() bug is related to that bug.

[Mariatta]

New changeset 6b7bc45 by Mariatta in branch '3.5':
bpo-29557: Remove ambiguous line in binhex docs (GH-90) (GH-474)
6b7bc45

[Mariatta]

New changeset 130c4ec by Mariatta in branch '3.6':
bpo-29557: Remove ambiguous line in binhex docs (GH-90) (GH-475)
130c4ec