problem in diffutils doc, re binary files

[Andrew Tannenbaum]

In the current diffutils doc:

http://www.gnu.org/software/diffutils/manual/html_node/Binary.html

there is this text:

===
You can also force diff to consider all files to be binary files, and
report only whether they differ (but not how). Use the -q or --brief
option for this.

Differing binary files are considered to cause trouble because the
resulting diff output does not capture all the differences. This
trouble causes diff to exit with status 2. However, this trouble
cannot occur with the --a or --text option, or with the -q or --brief
option, as these options both cause diff to treat binary files like
text files.
===

First of all the option is -a, not --a.  But that's not my real beef.

The first paragraph says that -q/--brief will make diff consider all
files to be [treated like] binary files.  The second paragraph says
that -q/--brief causes diff to treat binary files like text files.  I
think the first paragraph is right, and the second paragraph is messy.
 Was the phrase "or with the -q or --brief option," dropped into the
existing sentence without paying careful attention?

The intent here is probably to discuss the conditions that generate a
status 2, and how to avoid it.  Perhaps -a/--text and -q/--brief all
protect you from status 2, I'm not sure.

The man page says "2 means trouble."  This (second) paragraph is the
attempt to clarify that, but it's too messy.  I think the intent is to
say that status 2 means that diff started by assuming that the files
were texts, and later found binary data that will corrupt your diff
output if you use it as input to a patch-style tool.

Sorry this note isn't clearer, I hope it's helpful.

-Andy