bug#9531: md5sum: confusing documentation for file type output

[Jim Meyering]

Reuben Thomas wrote:

> On 17 September 2011 14:15, Jim Meyering <address@hidden> wrote:
>> Reuben Thomas wrote:
>>> The documentation says:
>>>
>>> The default mode is to print a line with checksum, a character
>>> indicating type (`*' for binary, `
>>>  ' for text), and name for each FILE.
>>>
>>> There are two problems here. First, a small one: the second character
>>> is a space character, which needs to be non-breaking, and preferably
>>> explained, as in "` ' (a space)". If you agree, I'll make a patch for
>>> the info and man page.
>>
>> Sure, thanks.  Though the man page renders fine for me,
>> with an 80-column-wide terminal:
>>
>>       input  should  be a former output of this program.  The default mode is
>>       to print a line with checksum, a character  indicating  type  (`*'  for
>>       binary, ` ' for text), and name for each FILE.
>>
>> Maybe it depends on terminal width?
>
> This is what I'm saying: with the wrong terminal width, the closing
> quote is on the line after the opening line, and this is possible
> because the contents of the quotes is a normal space. A non-breaking
> space is needed. And preferably the explanation I suggested, since ` '
> is apt to be mistaken for `'.
>
>> However, "... indicating type" refers to "type of checksum line",
>> or "type to be used for", not the type of the file.  It controls how
>> md5sum opens the file, but only on systems for which O_BINARY makes
>> a difference (which means it's not worth much discussion for
>> unix/linux/gnu-centric documentation).
>
> So how about something like s/indicating type/indicating the mode in
> which the file should be opened (this only matters for systems which
> treat text and binary files differently)/ ?

That makes the parenthetical bit so long that the affected sentence
is even harder to read.  How about simplifying "the default" case
and adding any additional information in a second sentence?

  The default mode (on systems that do not distinguish between binary
  and text files) is to print a line with checksum, two spaces
  and the name of each FILE.

We still have a pesky parenthetical because the default on that
other type of system is to treat everything as --binary and to
print the "*" indicator.