Bug#852015: diffoscope: Suggested improvements to --help output and CONTRIBUTING

[Brett Smith]

Source: diffoscope
Severity: minor
Tags: patch upstream

Dear Maintainer,

I've attached a series of patches to improve documentation, in the output of
`--help` and CONTRIBUTING.

This all started because I noticed `--list-tools` took an optional argument,
and I wasn't sure what a good value for LIST_TOOLS was.  I set out to
document that, and that's the first patch.

Then while I was at it I made a series of smaller improvements to the
`--help` output, mostly just making things internally consistent, like the
way metavars are written.  That's the second patch.

Since these aren't code bugs, I wasn't sure what the best way to submit them
was, so we had a brief chat about that at one of the reproducible builds
meetings a little while ago.  I've updated CONTRIBUTING based on our
conversation, encouraging people to send all patches and improvement
requests to the Debian BTS.  That's the third patch.

I took an action item to add something about reporting bugs to `--help`, but
in retrospect I'm not really sure that's right.  I think I read CONTRIBUTING
before, but because it suggested so many ways to submit improvements, I felt
unsure which to use.  I hope the third patch addresses the issue underlying
the action item, giving future contributors more direction about how to
submit improvements.

I've published my working branch at
<https://github.com/brettcs/diffoscope/tree/bcs-help-output> if that helps
to work with.

Thanks,

--Brett

-- System Information:
Debian Release: 8.6
  APT prefers stable-updates
  APT policy: (500, 'stable-updates'), (500, 'stable')
Architecture: amd64 (x86_64)

Kernel: Linux 4.9.0 (SMP w/4 CPU cores)
Locale: LANG=C, LC_CTYPE=C (charmap=UTF-8) (ignored: LC_ALL set to en_US.utf8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-diffoscope-Specify-choices-for-list-tools-switch.patch
Type: text/x-diff
Size: 3693 bytes
Desc: not available
URL: <http://lists.alioth.debian.org/pipermail/reproducible-builds/attachments/20170120/f2572d7b/attachment.patch>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0002-diffoscope-Copyedit-help-output.patch
Type: text/x-diff
Size: 9092 bytes
Desc: not available
URL: <http://lists.alioth.debian.org/pipermail/reproducible-builds/attachments/20170120/f2572d7b/attachment-0001.patch>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0003-CONTRIBUTING-Refresh-instructions-for-contributing-t.patch
Type: text/x-diff
Size: 3154 bytes
Desc: not available
URL: <http://lists.alioth.debian.org/pipermail/reproducible-builds/attachments/20170120/f2572d7b/attachment-0002.patch>