Bug#347732: pstoedit: help output and and manpage userUNfriendly
Eduard Bloch
Version: 3.33-15
Severity: minor
Hello,
I see useability as one of the criteria to estimate the program quality.
The rough estimate of it can be done by comparing the expectations of
DIN-EN-ISO-9241 with the user model of some program.
In this context, pstoedit badly fails. Why? I, as a dumb user in this
case, expect this tool to convert a ps file into an editable format. How
do I get when I read the -help output or the manpage? Not anything that
shows me how exactly to use this tool. The -help output should tell you
something like:
pstoedit <switch> <format> inputfile outputfile
Instead, it says "No backend specified". Fine. What should I do with
THAT MESSAGE? Question a) what is a backend, and b) how to specify it?
For a), I can guess that my output format is meant. But how to specify?
There is only a HUGE list of options and it is hard to see which
one is to specify the backend. Now I say "pstoedit | grep backend" and
what happens? Not what you expect, it puts the help message to STDERR
thouh -h is specified. WTF? We continue:
pstoedit 2>&1 | grep backend
No backend specified
<some options about backends but not saying how to specify it>
So what now? Let's read the manpage. Looking for "backend" and found...
nothing useful! Rereading the SYNOPSIS. Oh, fine, it is called "format"
this time. What is the different between backend and format? Oh, well,
it somehow becomes clear after reading two pages of other junk. Or not
so clear? It says -f format:options so I assume it means -f format:ps or
so. Or not? A quick test shows that "-f<format>:<format-options>" is
menat in the docs where format is the one from the list of backends.
Ok. But is that userfriendly? Most certainly not. So, please, consider
following things:
- keep the language/terminology consistent
- add example line to the usage, not only to the manpage
- sort the options according to their priority (in user's eyes), don't
throw most important options among rarely used ones. Consider doing
something like:
pstoedit: version 3.33 / DLL interface 108 (build Sep 3 2005 - release build) : Copyright (C) 1993 - 2003 Wolfgang Glunz
USAGE: pstoedit -f "<format>[:options]" <advanced opts> input-file [output-file]
Options:
-f <string> : target format identifier. Use -help to see available formats.
-page <int> : extract a specific page: 0 means all pages
- scale <double> : scale factor applied to the output
Advanced options:
<the long list of the less relevant options>
Last point: the descriptoin of the "-bo" option in the list of options
is odd. Please describe what it actually does, not only some possible
case of its usage. Eg. "Expect input to be in pstoedit's intermediate
format, not using other preprocessing. Useful to do: ...".
Eduard.
-- System Information:
Debian Release: testing/unstable
APT prefers unstable
APT policy: (500, 'unstable'), (1, 'experimental')
Architecture: i386 (i686)
Shell: /bin/sh linked to /bin/bash
Kernel: Linux 2.6.15
Locale: LANG=de_DE.UTF-8, LC_CTYPE=de_DE.UTF-8 (charmap=UTF-8)
--
To UNSUBSCRIBE, email to debian-bugs-...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listm...@lists.debian.org