From owner-freebsd-questions@freebsd.org Tue Sep 22 15:31:58 2020 Return-Path: Delivered-To: freebsd-questions@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 9EA8C3EC1EE for ; Tue, 22 Sep 2020 15:31:58 +0000 (UTC) (envelope-from freebsd@edvax.de) Received: from mout.kundenserver.de (mout.kundenserver.de [217.72.192.75]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-256) server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "mout.kundenserver.de", Issuer "TeleSec ServerPass Class 2 CA" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4BwlfP4QDyz49Pm for ; Tue, 22 Sep 2020 15:31:57 +0000 (UTC) (envelope-from freebsd@edvax.de) Received: from r56.edvax.de ([94.222.5.88]) by mrelayeu.kundenserver.de (mreue109 [212.227.15.183]) with ESMTPA (Nemesis) id 1MWRZt-1jwLtN1GcF-00Xp6k; Tue, 22 Sep 2020 17:31:50 +0200 Date: Tue, 22 Sep 2020 17:31:49 +0200 From: Polytropon To: David Christensen Cc: freebsd-questions@freebsd.org Subject: Re: Error message output Message-Id: <20200922173149.0c851c58.freebsd@edvax.de> In-Reply-To: <0dc8a3a4-85d9-7168-f118-b456aafd3910@holgerdanske.com> 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> <0dc8a3a4-85d9-7168-f118-b456aafd3910@holgerdanske.com> Reply-To: Polytropon Organization: EDVAX X-Mailer: Sylpheed 3.1.1 (GTK+ 2.24.5; i386-portbld-freebsd8.2) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-Provags-ID: V03:K1:y5lHHfr0QHuEDJ2a+4GMV74ZhCBbYZb7Ray3vC+OejsYfwNVUi9 jKWAjWiTUp5020P+c1NIbs/NmgzKRC3vgXbmmHAv+OOXNHDEWi2d0+N1p/ncg7OyF6Q5eCC ZPWlhm1Q+XMzl2rMYqGI35GzCs6UNjpFqA74C7qlMaO7jexZcr6ldQbxJQeKK+or6XSSYw5 LLmTcdEtt7YFfblk9q2gQ== X-Spam-Flag: NO X-UI-Out-Filterresults: notjunk:1;V03:K0:SdUdGFtSwrA=:n5YYwxKt6yaydPuai8EZaX vh5e72aQ+EmqvqUd5vB6nsF5zQ71T0e2sFAh3mSOX0JIUKGF6rJIx9L9rP/dPYdbB5CGvKN6a YMtIzD8V4uLBA+jwcrTZoWtW4zQoGzDoYwnNxYai30IJqNLVVZJ2nWXTfgY6Zy+6Y5cfNZzlx R5vBVR9tz80rpcNWLP01oW6sEpk/ZIEhPRgSoqfQVJEy1naF0zdMT6XcbN21QqURzcttBObzi NxcgszfcD8TqgAly+e2971V+Iu5HYCtglkKWn2s22VqjzoLXVVeJajkgWaID1Aoj1iwzqTJ6q uj0Q0kvp3spTlJtjVDZh5AeQhanXpPoqtUw73UuSgVJUnHc/T8RowuQAH/7svq2+cwtiQ7Erz wLdfM5H/1hIaB/P0OK0kqL1XJ4IrmonYzevr+k0pjL7vBzpZoma7zNhNuUZYqZOmjEQHcPwjs RckmSnmWUo/IkbGwXrM712CXBBLft9yvgD6OiPOVZMg+vsyB5KBw3xesOMakiPp/gnji1Fx/7 1FrZj1pv1mcGecet57DHfF8F4TOEA482m3jeD87eo2cN7N4jhjKhxxaXM/dsWJPQko9EyTV/K tD+BWupzbR+LvLuux2/06X/0LF70BjQuWg5T2w0otZWf2XU+5eq71dtxn9CfHnQPbz/b2pFgD IHysLNqCw3iLTPQrmhIGUyxTtk1QLH4VAJtcmhXGWwQ3PgKZ0UlHuXdY73BV0mJWBXThFHLIT OTrJG0H65VBUBEJdFQV08xGsYMMMRUcf2t9/o4hfzJ2q0QMvnw47eEsCYIOwxSw7Z8H1zGA40 VskXA5PrnHL6PdUeRCYp00uzdVGeGejcFSRnPZDGWrCbfHlMBWzG7cR/J/LTW7FxyV6jYhH X-Rspamd-Queue-Id: 4BwlfP4QDyz49Pm X-Spamd-Bar: / Authentication-Results: mx1.freebsd.org; dkim=none; dmarc=none; spf=none (mx1.freebsd.org: domain of freebsd@edvax.de has no SPF policy when checking 217.72.192.75) smtp.mailfrom=freebsd@edvax.de X-Spamd-Result: default: False [0.58 / 15.00]; HAS_REPLYTO(0.00)[freebsd@edvax.de]; RCVD_VIA_SMTP_AUTH(0.00)[]; TO_DN_SOME(0.00)[]; MV_CASE(0.50)[]; HAS_ORG_HEADER(0.00)[]; NEURAL_HAM_SHORT(-0.01)[-0.013]; RCPT_COUNT_TWO(0.00)[2]; RECEIVED_SPAMHAUS_PBL(0.00)[94.222.5.88:received]; RCVD_TLS_LAST(0.00)[]; R_DKIM_NA(0.00)[]; FROM_EQ_ENVFROM(0.00)[]; MIME_TRACE(0.00)[0:+]; ASN(0.00)[asn:8560, ipnet:217.72.192.0/20, country:DE]; ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-0.86)[-0.857]; REPLYTO_EQ_FROM(0.00)[]; FROM_HAS_DN(0.00)[]; NEURAL_HAM_LONG(-0.96)[-0.955]; MIME_GOOD(-0.10)[text/plain]; DMARC_NA(0.00)[edvax.de]; AUTH_NA(1.00)[]; TO_MATCH_ENVRCPT_SOME(0.00)[]; MID_CONTAINS_FROM(1.00)[]; RCVD_IN_DNSWL_NONE(0.00)[217.72.192.75:from]; R_SPF_NA(0.00)[no SPF record]; RWL_MAILSPIKE_POSSIBLE(0.00)[217.72.192.75:from]; RCVD_COUNT_TWO(0.00)[2]; MAILMAN_DEST(0.00)[freebsd-questions] X-BeenThere: freebsd-questions@freebsd.org X-Mailman-Version: 2.1.33 Precedence: list List-Id: User questions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 22 Sep 2020 15:31:58 -0000 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? > > > 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? Correct: You provide a "pattern" (i. e., "starts with", the shell does the expansion of *), and the output file drops the "counter" and is a PDF file containing the scanned sheets, so it's easier to transfer and print. :-) > I would drop the '.sh' extension. Will do, especially as it's now in /opt/bin, a reason to be optimistic. :-) > 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. In this case, the calling shell would have to do it. I do not expect csh or bash or zsh doing that differently from plain sh, but you never know... :-) > 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. Programs like cpio do this. 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". > 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 The key is that the output filename is "automatically" assigned ("base name without counter"). In such a case, I'd even go for an optional argument for the output file, such as cc does: % cc blah.c generates a.out, but % cc -o blah blah.c generates blah as the output binary; -o is optional. > 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 The advantage of having the invoking shell define the input files is that it enables the user to combine files with different "base names", such as: % png2pdf -o report.pdf blah_01.png blah_02.png foo_*.png end.png I think this is a good idea for further improvement. Both concepts also work nicely with shell completition: % png2pdf foo[TAB] png2pdf foo_2020-01-23_ png2pdf foo_2020-01-23_*.png In case there are no offending files of other types, "*" can be the last symbol. > 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... 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 ":=". ;-) > 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. > 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. 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. > > 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... 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. :-) > > % png2pdf.sh > > Convert PNG image files and create PDF > > Usage: /opt/bin/png2pdf.sh > > The source file pattern must lead to files named _*.png. > > The target file's name will be .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. For the tool in question, the usage message would be the default, as one cannot assume any valid input. :-) Thank you for inspiration and further education. It's always nice to learn something new or reconsider something learned and / or long forgotten. -- Polytropon Magdeburg, Germany Happy FreeBSD user since 4.0 Andra moi ennepe, Mousa, ...