--- Begin Message ---
|
Subject: |
md5sum: confusing documentation for file type output |
|
Date: |
Sat, 17 Sep 2011 14:01:31 +0100 |
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.
Secondly, looking at the code, this isn't really what md5sum does.
Rather, it prints '*' if in binary mode (--binary, or if O_BINARY is
non-zero), and ' ' if in text mode (--text, or if O_BINARY is zero),
but doesn't actually look at the file. It's not obvious to me why it's
useful to output what mode md5sum is in (rather than doing some
analysis of the file) but something needs changing here, whether it's
behavior or documentation.
--
http://rrt.sc3d.org
--- End Message ---
--- Begin Message ---
|
Subject: |
Re: bug#9531: md5sum: confusing documentation for file type output |
|
Date: |
Mon, 19 Sep 2011 11:41:08 +0200 |
Reuben Thomas wrote:
> I attach a patch which makes simpler changes than those I suggested
> before. In particular, for the man page I just replaced "` '" with
> "space" because I can't see a way to put a non-breaking space into
> help text which will then also work in the man page after going
> through help2man (perhaps a Unicode non-breaking space would work, but
> it doesn't seem sensible to try!).
>
>>From bd0ed380c7050a1b55fca71da075fd9853442b1c Mon Sep 17 00:00:00 2001
> From: Reuben Thomas <address@hidden>
> Date: Sat, 17 Sep 2011 16:05:17 +0100
> Subject: [PATCH] md5sum: clarify what is meant by binary/text flag.
>
> src/md5sum.c: Clarify that we are talking about input mode.
> doc/coreutils.texi: Ditto.
Thanks.
I've applied that with the log adjusted to conform:
doc: clarify what is meant by md5sum's binary/text flag
* src/md5sum.c (usage): Clarify that we are talking about input mode.
* doc/coreutils.texi (md5sum invocation): Ditto.
Changes:
- leading "doc: " so this doesn't look like an md5sum bug fix
- neither capitalized first word nor period at end of summary line
- left-justified "*" for each file-starting ChangeLog entry.
If you use vc-dwim and emacs' 'C-x 4 a', it'll insert the
"* FILE_NAME (FUNCTION_NAME):" for each file in your ChangeLog.
See vc-dwim's --help output for how to convert each new ChangeLog
entry into a commit log. Plus, it provides a handy cross-check,
to ensure that files listed in ChangeLog are also in the commit,
and don't have pending-but-not-written-to-disk changes.
- "(parenthesized function or section name)" after each file name.
--- End Message ---