Error message output

[David Christensen]

On 2020-09-22 08:31, Polytropon wrote:
> On Mon, 21 Sep 2020 23:33:50 -0700, David Christensen wrote:
>> 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?

> Programs that operate on a set of
> files typically get them via command line, while programs that
> operate on _one_ file from a set of file often have their "list
> generator" prefixed, like "something | xargs -n 1 progname".

Agreed.


>> My scripts emit '+' in the first position only when they have invoked
>> sh(1) with xtrace enabled.  Outputting '+' otherwise is confusing.
> 
> Never heared of that concept...

2020-09-22 17:07:49 dpchrist at f3 ~/sandbox/sh
$ freebsd-version; uname -a
12.1-RELEASE-p8
FreeBSD f3.tracy.holgerdanske.com 12.1-RELEASE-p8 FreeBSD 
12.1-RELEASE-p8 GENERIC  amd64

2020-09-22 17:07:57 dpchrist at f3 ~/sandbox/sh
$ man sh | grep -A 4 xtrace
      -x xtrace
              Write each command (preceded by the value of the PS4
              variable subjected to parameter expansion and arithmetic
              expansion) to standard error before it is executed.  Useful
              for debugging.

2020-09-22 17:08:06 dpchrist at f3 ~/sandbox/sh
$ echo $PS4
+

2020-09-22 17:08:11 dpchrist at f3 ~/sandbox/sh
$ cat freebsd-questions-polytropon-20200922-0831.sh
#!/bin/sh

echo "invoking echo from script"

/bin/sh -x -c 'echo "invoking /bin/sh with xtrace to invoke echo"'

2020-09-22 17:08:17 dpchrist at f3 ~/sandbox/sh
$ /bin/sh freebsd-questions-polytropon-20200922-0831.sh
invoking echo from script
+ echo 'invoking /bin/sh with xtrace to invoke echo'
invoking /bin/sh with xtrace to invoke echo


Things get more interesting when you have scripts calling scripts 
calling scripts, etc..  I avoid obfuscating $PS4 / '+'.


> I thought it was good to use "+" for "adding", and "->" for "to
> the result"; maybe "=" or even ":=" would have been possible too,
> even though I tried hard to unlearn ":=". ;-)

Using punctuation for computer code, commands, input, output, etc., is a 
mixed blessing.  It is concise, but:

1.  Too many people have created too many "punctuated languages", each 
with different meaning and semantics.  A new reader must learn each new 
language and an old reader must remember many.  Trying to understand one 
listing that contains several such languages is a good way to get a 
headache.

2.  Punctuation usually prevents using the output of one program as the 
input to another program -- thus breaking the Unix filter/ pipeline model.


Thus, my suggestions of textual/ word prefaces, sending verbose messages 
to stderr, and printing bare output file names to stdout.  Now you can 
pipe the output of png2pdf to xargs(1), which invokes another program 
that operates on PDF files.


>> 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.
> 
> Or the opposite approach: -q (quiet) if you don't want those.
> Or compare cp to cp -v.

2020-09-22 16:35:29 dpchrist at f3 ~/sandbox/sh
$ touch foo

2020-09-22 16:35:32 dpchrist at f3 ~/sandbox/sh
$ cp foo bar

2020-09-22 16:35:46 dpchrist at f3 ~/sandbox/sh
$ cp -v foo baz
foo -> baz


So, non-verbose cp(1) displays nothing and verbose cp(1) displays both 
input and output file names.


But, cp(1) is one-to-one and png2pdf is many-to-one.  Emulating the 
style of cp(1) with a lot of input files would produce very long lines. 
I will stick with my suggestions, above.


>> For exit value, I use 0 for correct operation and 1 for everything else.
> 
> As suggested by sysexits.h, it's possible to signal the kind
> of error to the caller. This is not standard in sh scripts,
> but can be used there.

I use Bourne shell scripts for simple tasks and Perl when I need more. 
Generating an error message, dumping the relevant variables, and exiting 
with non-zero is usually enough in both cases.


>>       Usage: png2pdf.sh [-v] [-q] infile... outfile
>>              png2pdf.sh [-v] [-q] [-O outfile] infile...
> 
> That is correct, and the system tools tend to follow that
> convention. Existing man pages and the templates suggest
> this style. Oh, and I should probably write a manpage, too. :-)

FreeBSD usage messages seem to be terse reminders -- the explanations 
and details are in the manual pages.  I like that style.


If I need a manual page, I don't mind a non-compliant shell script usage 
message with extra information.  If the program needs a manual page, 
it's probably already Perl and I'll use Pod::Usage.


> Thank you for inspiration and further education. It's
> always nice to learn something new or reconsider something
> learned and / or long forgotten.

It's good to discuss these things.  :-)


David