Skip site navigation (1)Skip section navigation (2)
Date:      Mon, 21 Sep 2020 23:33:50 -0700
From:      David Christensen <dpchrist@holgerdanske.com>
To:        freebsd-questions@freebsd.org
Subject:   Re: Error message output
Message-ID:  <0dc8a3a4-85d9-7168-f118-b456aafd3910@holgerdanske.com>
In-Reply-To: <20200922005552.4df3c123.freebsd@edvax.de>
References:  <20200920191108.22864e5c.freebsd@edvax.de> <528b2c90-18c4-9e95-a150-67344154c66c@holgerdanske.com> <20200921132139.286b5bda.freebsd@edvax.de> <8b426d6f-6ebe-d1a7-13af-69cffbcb6222@holgerdanske.com> <20200922005552.4df3c123.freebsd@edvax.de>

Next in thread | Previous in thread | Raw E-Mail | Index | Archive | Help
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 
options:

     % 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 
error messages.


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.


David



Want to link to this message? Use this URL: <http://docs.FreeBSD.org/cgi/mid.cgi?0dc8a3a4-85d9-7168-f118-b456aafd3910>