[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#9531: md5sum: confusing documentation for file type output
From: |
Jim Meyering |
Subject: |
bug#9531: md5sum: confusing documentation for file type output |
Date: |
Sat, 17 Sep 2011 15:32:53 +0200 |
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.
- bug#9531: md5sum: confusing documentation for file type output, (continued)
- bug#9531: md5sum: confusing documentation for file type output, Eric Blake, 2011/09/17
- bug#9531: md5sum: confusing documentation for file type output, Rüdiger Meier, 2011/09/17
- bug#9531: md5sum: confusing documentation for file type output, Rüdiger Meier, 2011/09/17
- bug#9531: md5sum: confusing documentation for file type output, Eric Blake, 2011/09/17
- bug#9531: md5sum: confusing documentation for file type output, Jim Meyering, 2011/09/17
- bug#9531: md5sum: confusing documentation for file type output, Rüdiger Meier, 2011/09/17
- bug#9531: md5sum: confusing documentation for file type output, Alan Curry, 2011/09/17
- bug#9531: md5sum: confusing documentation for file type output, Rüdiger Meier, 2011/09/17
bug#9531: md5sum: confusing documentation for file type output, Jim Meyering, 2011/09/17