On Sat, 21 Jul 2007 16:52:59 +0900
Daiki Ueno <[EMAIL PROTECTED]> wrote:
> > Let's throw a changelog at 'treil':
>
> > % gunzip < /usr/share/doc/treil/changelog.Debian.gz > /tmp/chl
> > % treil -R ChangeLogReader /tmp/chl /tmp/chl.png ; echo $?
> > Reader: ChangeLogReader
> > Writer: CairoPNGWriter
> > failed to generate `/tmp/chl.png': divided by 0
> > /usr/lib/ruby/1.8/treil/reader.rb:107:in `/'
> > /usr/lib/ruby/1.8/treil/reader.rb:107:in
> > `set_background_by_timestamp' /usr/lib/ruby/1.8/treil/reader.rb:323:in
> > `read' /usr/bin/treil:111
> > 0
>
> This is not a bug.
^
One might argue that the above output shows not _A_ (single) bug, but
several distinct bugs.
> Your usage is wrong.
> ChangeLogReader (and other readers) takes directories rather than
> files.
Thanks, I didn't know that.
Still, "wrong" is a somewhat relative term here -- we bug reporters
tend to deliberately do things "wrong" in order to break programs.
Often bad usages reveal additional bugs in the error messages
themselves. For example, poor documentation:
% treil 2>&1 | head -n 2
Usage: /usr/bin/treil [OPTIONS] INPUT OUTPUT
Readers: CVSReader SVNReader GitReader HgReader ChangeLogReader
DirReader
% man treil | grep -A 1 SYN
SYNOPSIS
treil [OPTIONS]
Those should say that 'INPUT' has to be a directory, e.g.:
cd: cd [-L|-P] [dir]
Therefore:
Usage: /usr/bin/treil [OPTIONS] DIRECTORY OUTPUTFILE
treil [OPTIONS] DIRECTORY
Error messages should be more instructive. "divided by 0" implies
that a subprogram or library was called with bad syntax -- that's
virtually never the user's fault. The code should check for bad syntax
_before_ calling a fragile subroutine.
Since 'INPUT' should be a directory, it's trivial to check for,
e.g. in shell script:
[ ! -d $inp ] && { echo "$inp is not a directory" ; exit 2 ; }
> i.e. it is a fallback reader in case they are not version
> controlled.
I don't know what it does. It'd be better if the docs had some
sample usages that require only files already on the average Debian
system. Add an "example" directory to '/usr/share/doc/treil' if need
be.
> > In any event the exit code of '0' seems inappropriate.
>
> Perhaps.
For command line utils, bad input genrally results in an error code:
% ls -z ; echo $?
ls: invalid option -- z
Try `ls --help' for more information.
2
% man -z man > /dev/null ; echo $?
man: invalid option -- z
1
% cp -z /bin/sh /tmp/sh ; echo $?
cp: invalid option -- z
Try `cp --help' for more information.
1
HTH...
PS: Would you prefer the above comments were opened as separate bugs?
1) docs
a) vague SYNOPSIS & --help
b) examples (wishlist)
2) needlessly obscure error message
3) exit code 0
--
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
