expand script functionality

[zpackage] / doc / zpm-script.8

diff --git a/doc/zpm-script.8 b/doc/zpm-script.8
index bf5bbb77090696d5a4208dc8ab9e58ecc2b6bf97..97d1a9a61dae48a7b4beebb243998046a078e74c 100644 (file)
--- a/doc/zpm-script.8
+++ b/doc/zpm-script.8
@@ -1,10 +1,10 @@
-.TH zpm-script 8 2019-02-15 "ZPM 0.3"
+.TH zpm-script 8 2019-03-06 "ZPM 0.7.0"
 .SH NAME
 zpm-script \- run, set, or list package scripts
 .SH SYNOPSIS
 .B zpm script
 [
-.B -Fhq
+.B -Fhql
 ]
 [
 .BI -f " pkgfile"
@@ -22,6 +22,9 @@ zpm-script \- run, set, or list package scripts
 .BI -S " script"
 ]
 .I package
+[
+.I arg
+]
 .SH DESCRIPTION
 \fBzpm-script\fR
 runs, sets, or lists package scripts for a package.  The package is a package
@@ -38,8 +41,11 @@ to /var/tmp/zpm-script.out, or as specified by the -o option.
 The script itself will be extracted to /var/tmp/zpm-script, set as executable,
 and then run.  The script is run with one or two arguments.  The
 first argument is the package id being installed, removed, or configured.
-For a package version update (or downgrade) the second argument is
-the previous version of the package.
+If given \fIarg\fR is passed to the script as a second argument.
+For a package version update (or downgrade) this is the previous version of the
+package.
+.PP If the script fails (i.e. any non-zero exit status), the output will
+be imported into the database and a note will be added.
 .TP
 An example script
 .EX
@@ -53,12 +59,40 @@ Set mode will set the script for a given package and phase to the
 path given as an additional argument.  If the -h is given, the script
 is interpreted as a hash to be set directly, and nothing is taken
 from the filesystem.
+.SS List Mode
+If a phase is given with \-p the script will be printed to stdout (or
+wherever \-o specifies).  If no phase is given, a list of scripts for
+the package will be printed to stdout.
 .SH OPTIONS
 .TP
+.B \-l
+Run in list mode.
+.TP
+.B \-r
+Run in run mode.  This is the default.
+.TP
+.B \-s
+Run in set mode.
+.TP
 .BI \-p phase
 Specify the script phase.  This defaults to all phases for list mode,
 and configure for running or setting scripts.
 .TP
+.B \-n
+Do not create notes.  Overrides other note options.
+.TP
+.B \-N
+Create notes only if the database is writable, otherwise send
+output to stdout.
+.TP
+.B \-a
+Make a note for all output, regardless of the exit status.
+.TP
+.B \-e
+Allow empty notes to be created for the \-a option.
+Normally if the output is empty and the script succeeded, the \-a option
+will not cause a note to be created.
+.TP
 .B \-f
 specify the package file to find packages in
 .TP
@@ -68,6 +102,18 @@ than a path to a script.
 .TP
 .B \-q
 Run quietly.
+.TP
+.B \-v
+Send any output to stdout.
+.TP
+.BI \-R " rootdir"
+The current directory will be changed to \fIrootdir\fR before
+running the script.  Defaults to '/'.  No chroot is done
+before running the script, so scripts should be aware of this
+and generally use relative paths.  If neccessary and possible
+the script itself can chroot.  Calling chroot(2) requires superuser
+privileges, so it would be impossible to run the scripts as a non
+root user if chroot was attempted.
 .SH EXAMPLES
 .TP
 zpm script -f foo-1.0-1.zpm foo
@@ -77,6 +123,9 @@ file.
 zpm script foo
 Run the configure script for the (most recent) foo package found
 in the local database.
+.TP
+zpm script -l foo
+List all scripts for the foo package.
 .SH EXIT STATUS
 0 on success non zero on failure
 .SH FILES