Error message output
dpchrist at holgerdanske.com
Tue Sep 22 06:34:00 UTC 2020
On 2020-09-21 15:55, Polytropon wrote:
> On Mon, 21 Sep 2020 15:33:40 -0700, David Christensen wrote:
>> On 2020-09-21 04:21, Polytropon wrote:
>>> On Sun, 20 Sep 2020 22:12:24 -0700, David Christensen wrote:
>>>> On 2020-09-20 10:11, Polytropon wrote:
>>>>> I have a general question. Is it still considered useful to
>>>>> output error messages of a script to standard error?
> Example (from a real script); the following normal usage
> prints to standard output:
> % png2pdf.sh mdcc_rg_2020-04-01
> + mdcc_rg_2020-04-01_1.png
> + mdcc_rg_2020-04-01_2.png
> + mdcc_rg_2020-04-01_3.png
> -> mdcc_rg_2020-04-01.pdf
So, png2pdf.sh reads mdcc_rg_2020-04-01_1.png, mdcc_rg_2020-04-01_2.png,
and mdcc_rg_2020-04-01_3.png, and writes mdcc_rg_2020-04-01.pdf?
I would drop the '.sh' extension.
Providing a fractional base file name as an argument and computing input
and output file names is unconventional. The FreeBSD convention seems
to be to use complete file names for arguments. This allows the user to
use shell globbing, find(1) and xargs(1), etc., or to wrap this script
in another script that computes the arguments.
As this program operates on entire files and those files are binary, it
is tempting to allow input file names on stdin. I think this idea is
unconventional and better avoided.
So, I'd go with positional arguments for the input and output file names.
% png2pdf mdcc_rg_2020-04-01*.png mdcc_rg_2020-04-01.pdf
When the argument list contains two (or more) kinds of things, it can be
useful to pick one kind for arguments and to pass everything else via
% png2pdf -O mdcc_rg_2020-04-01.pdf mdcc_rg_2020-04-01*.png
My scripts emit '+' in the first position only when they have invoked
sh(1) with xtrace enabled. Outputting '+' otherwise is confusing.
If I wanted to see the input file names as they were processed, I would
add a verbose option and preface each input file name with "reading".
The messages would to to stderr.
My similar scripts typically print (to stdout) the bare names of files
and directories that they change. If there were multiple possibilities
-- "writing", "appending", "creating", "updating", "deleting", etc. -- I
would add prefaces. The messages would go to stdout.
Messages for files that are not changed would be handled by verbose
option messages -- "skipping", etc.. The messages would to to stderr.
It is nice to have a quiet option suppresses all output except fatal
For exit value, I use 0 for correct operation and 1 for everything else.
> The typical error cases (input not found, no input specified)
> output to standard error, and there is a non-zero exit code:
> % png2pdf.sh nothing
> Error: no matching source files for pattern nothing_*.png found, aborting.
The FreeBSD convention seems to be to print the usage message when given
bad options or arguments:
Usage: png2pdf.sh [-v] [-q] infile... outfile
png2pdf.sh [-v] [-q] [-O outfile] infile...
> % png2pdf.sh
> Convert PNG image files and create PDF
> Usage: /opt/bin/png2pdf.sh <pattern>
> The source file pattern must lead to files named <pattern>_*.png.
> The target file's name will be <pattern>.pdf.
When given no options or arguments, the FreeBSD convention seems to be
to run the program with a default argument. If no default makes sense,
then to print the usage message.
More information about the freebsd-questions