man: Add basic maintainer script man pages

These document the bare minimum, with a brief description of the
maintainer scripts and the ways they can get called.

debian/changelog

@@ -10,6 +10,8 @@ dpkg (1.18.11) UNRELEASED; urgency=medium
       Prompted by Johannes Schauer <josch@debian.org>.
     - Document the .changes filename that dpkg-buildpackage generates in
       dpkg-buildpackage(1). Prompted by Johannes Schauer <josch@debian.org>.
+    - Add basic maintainer script man pages: deb-postinst(5), deb-postrm(5),
+      deb-preinst(5) and deb-prerm(5).
   * Build system:
     - Add support for profiling perl modules.
     - Clean up compiler and linker automatic flag usage in configure.

debian/dpkg-dev.manpages

@@ -11,6 +11,10 @@ debian/tmp/usr/share/man/*/deb-extra-override.5
 debian/tmp/usr/share/man/*/deb-shlibs.5
 debian/tmp/usr/share/man/*/deb-split.5
 debian/tmp/usr/share/man/*/deb-symbols.5
+debian/tmp/usr/share/man/*/deb-postinst.5
+debian/tmp/usr/share/man/*/deb-postrm.5
+debian/tmp/usr/share/man/*/deb-preinst.5
+debian/tmp/usr/share/man/*/deb-prerm.5
 debian/tmp/usr/share/man/*/deb-triggers.5
 debian/tmp/usr/share/man/*/deb-old.5
 debian/tmp/usr/share/man/*/deb.5

debian/dpkg-dev.preinst

@@ -1,18 +1,5 @@
 #!/bin/sh
-# This script can be called in the following ways:
-#
-# Before the package is installed:
-#	<new-preinst> install
-#
-# Before removed package is upgraded:
-#	<new-preinst> install <old-version>
-#
-# Before the package is upgraded:
-#	<new-preinst> upgrade <old-version>
-#
-#
-# If postrm fails during upgrade or fails on failed upgrade:
-#	<old-preinst> abort-upgrade <new-version>
+# See deb-preinst(5).
 
 set -e
 

debian/dpkg.postinst

@@ -1,25 +1,5 @@
 #!/bin/sh
-# This script can be called in the following ways:
-#
-# After the package was installed:
-#	<postinst> configure <old-version>
-#
-# After the package was triggered:
-#	<postinst> triggered <trigger-name>…
-#
-#
-# If prerm fails during upgrade or fails on failed upgrade:
-#	<old-postinst> abort-upgrade <new-version>
-#
-# If prerm fails during removal:
-#	<old-postinst> abort-remove
-#
-# If prerm fails during deconfiguration of a package:
-#	<postinst> abort-deconfigure in-favour <new-package> <version>
-#		   removing <old-package> <version>
-#
-# If prerm fails during replacement due to conflict:
-#	<postinst> abort-remove in-favour <new-package> <version>
+# See deb-postinst(5).
 
 set -e
 

debian/dpkg.postrm

@@ -1,30 +1,5 @@
 #!/bin/sh
-# This script can be called in the following ways:
-#
-# After the package was removed:
-#	<postrm> remove
-#
-# After the package was purged:
-#	<postrm> purge
-#
-# After the package was upgraded:
-#	<old-postrm> upgrade <new-version>
-# if that fails:
-#	<new-postrm> failed-upgrade <old-version> <new-version>
-#
-#
-# After all of the packages files have been replaced:
-#	<postrm> disappear <overwriting-package> <version>
-#
-#
-# If preinst fails during install:
-#	<new-postrm> abort-install
-#
-# If preinst fails during upgrade of removed package:
-#	<new-postrm> abort-install <old-version> <new-version>
-#
-# If preinst fails during upgrade:
-#	<new-postrm> abort-upgrade <old-version> <new-version>
+# See deb-postrm(5).
 
 set -e
 

debian/dpkg.preinst

@@ -1,18 +1,5 @@
 #!/bin/sh
-# This script can be called in the following ways:
-#
-# Before the package is installed:
-#	<new-preinst> install
-#
-# Before removed package is upgraded:
-#	<new-preinst> install <old-version> <new-version>
-#
-# Before the package is upgraded:
-#	<new-preinst> upgrade <old-version> <new-version>
-#
-#
-# If postrm fails during upgrade or fails on failed upgrade:
-#	<old-preinst> abort-upgrade <new-version>
+# See dpkg-preinst(5).
 
 set -e
 

debian/dpkg.prerm

@@ -1,21 +1,5 @@
 #!/bin/sh
-# This script can be called in the following ways:
-#
-# Before the package is removed:
-#      <prerm> remove
-#
-# Before an upgrade:
-#      <old-prerm> upgrade <new-version>
-# if that fails:
-#      <new-prerm> failed-upgrade <old-version> <new-version>
-#
-#
-# Before package is deconfigured while dependency is replaced due to conflict:
-#      <prerm> deconfigure in-favour <new-package> <version>
-#              removing <old-package> <version>
-#
-# Before the package is replaced due to conflict:
-#      <prerm> remove in-favour <new-package> <version>
+# See deb-prerm(5).
 
 set -e
 

debian/dselect.preinst

@@ -1,18 +1,5 @@
 #!/bin/sh
-# This script can be called in the following ways:
-#
-# Before the package is installed:
-#	<new-preinst> install
-#
-# Before removed package is upgraded:
-#	<new-preinst> install <old-version>
-#
-# Before the package is upgraded:
-#	<new-preinst> upgrade <old-version>
-#
-#
-# If postrm fails during upgrade or fails on failed upgrade:
-#	<old-preinst> abort-upgrade <new-version>
+# See deb-preinst(5).
 
 set -e
 

man/Makefile.am

@@ -11,6 +11,10 @@ dist_man_MANS = \
 	deb-split.5 \
 	deb-substvars.5 \
 	deb-symbols.5 \
+	deb-postinst.5 \
+	deb-postrm.5 \
+	deb-preinst.5 \
+	deb-prerm.5 \
 	deb-triggers.5 \
 	deb-old.5 \
 	deb-origin.5 \

man/deb-postinst.5

@@ -0,0 +1,53 @@
+.\" dpkg manual page - deb-postinst(5)
+.\"
+.\" Copyright © 2016 Guillem Jover <guillem@debian.org>
+.\"
+.\" This is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program.  If not, see <https://www.gnu.org/licenses/>.
+.
+.TH deb\-postinst 5 "2016-08-16" "Debian Project" "dpkg utilities"
+.SH NAME
+deb\-postinst \- package post-installation maintainer script
+.
+.SH SYNOPSIS
+postinst
+.
+.SH DESCRIPTION
+A package can perform several post-installation actions via maintainer
+scripts, by including an executable \fIpostinst\fP file in its control
+archive (i.e. \fIDEBIAN/postinst\fP during package creation).
+.PP
+The script can be called in the following ways:
+.TP
+\fIpostinst\fP \fBconfigure\fP \fIold-version\fP
+After the package was installed.
+.TP
+\fIpostinst\fP \fBtriggered\fP \fItrigger-name...\fP
+After the package was triggered.
+.TP
+\fIold-postinst\fP \fBabort-upgrade\fP \fInew-version\fP
+If \fIprerm\fP fails during upgrade or fails on failed upgrade.
+.TP
+\fIold-postinst\fP \fBabort-remove\fP
+If \fIprerm\fP fails during removal.
+.TP
+\fIpostinst\fP \fBabort-deconfigure in-favour\fP \fInew-package new-version\fP
+.TQ
+       [ \fBremoving\fP \fIold-package old-version\fP ]
+If \fIprerm\fP fails during deconfiguration of a package.
+.TP
+\fIpostinst\fP \fBabort-remove in-favour\fP \fInew-package new-version\fP
+If \fIprerm\fP fails during replacement due to conflict.
+.
+.SH SEE ALSO
+.BR dpkg (1).

man/deb-postrm.5

@@ -0,0 +1,57 @@
+.\" dpkg manual page - deb-postrm(5)
+.\"
+.\" Copyright © 2016 Guillem Jover <guillem@debian.org>
+.\"
+.\" This is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program.  If not, see <https://www.gnu.org/licenses/>.
+.
+.TH deb\-postrm 5 "2016-08-16" "Debian Project" "dpkg utilities"
+.SH NAME
+deb\-postrm \- package post-removal maintainer script
+.
+.SH SYNOPSIS
+postrm
+.
+.SH DESCRIPTION
+A package can perform several post-removal actions via maintainer
+scripts, by including an executable \fIpostrm\fP file in its control
+archive (i.e. \fIDEBIAN/postrm\fP during package creation).
+.PP
+The script can be called in the following ways:
+.TP
+\fIpostrm\fP \fBremove\fP
+After the package was removed.
+.TP
+\fIpostrm\fP \fBpurge\fP
+After the package was purged.
+.TP
+\fIold-postrm\fP \fBupgrade\fP \fInew-version\fP
+After the package was upgraded.
+.TP
+\fInew-postrm\fI \fBfailed-upgrade\fP \fIold-version new-version\fP
+If the above \fBupgrade\fP call fails.
+.TP
+\fIpostrm\fP \fBdisappear\fP \fIoverwriter-package\fP \fIoverwriter-version\fP
+After all of the packages files have been replaced.
+.TP
+\fInew-postrm\fP \fBabort-install\fP
+If \fIpreinst\fP fails during install.
+.TP
+\fInew-postrm\fP \fBabort-install\fP \fIold-version new-version\fP
+If \fIpreinst\fP fails during upgrade of removed package.
+.TP
+\fInew-postrm\fP \fBabort-upgrade\fP \fIold-version new-version\fP
+If \fIpreinst\fP fails during upgrade.
+.
+.SH SEE ALSO
+.BR dpkg (1).

man/deb-preinst.5

@@ -0,0 +1,45 @@
+.\" dpkg manual page - deb-preinst(5)
+.\"
+.\" Copyright © 2016 Guillem Jover <guillem@debian.org>
+.\"
+.\" This is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program.  If not, see <https://www.gnu.org/licenses/>.
+.
+.TH deb\-preinst 5 "2016-08-16" "Debian Project" "dpkg utilities"
+.SH NAME
+deb\-preinst \- package pre-installation maintainer script
+.
+.SH SYNOPSIS
+preinst
+.
+.SH DESCRIPTION
+A package can perform several pre-installation actions via maintainer
+scripts, by including an executable \fIpreinst\fP file in its control
+archive (i.e. \fIDEBIAN/preinst\fP during package creation).
+.PP
+The script can be called in the following ways:
+.TP
+\fInew-preinst\fP \fBinstall\fP
+Before the package is installed.
+.TP
+\fInew-preinst\fP \fBinstall\fP \fIold-version new-version\fP
+Before removed package is upgraded.
+.TP
+\fInew-preinst\fP \fBupgrade\fP \fIold-version new-version\fP
+Before the package is upgraded.
+.TP
+\fIold-preinst\fP \fBabort-upgrade\fP \fInew-version\fP
+If \fIpostrm\fP fails during upgrade or fails on failed upgrade.
+.
+.SH SEE ALSO
+.BR dpkg (1).

man/deb-prerm.5

@@ -0,0 +1,50 @@
+.\" dpkg manual page - deb-prerm(5)
+.\"
+.\" Copyright © 2016 Guillem Jover <guillem@debian.org>
+.\"
+.\" This is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program.  If not, see <https://www.gnu.org/licenses/>.
+.
+.TH deb\-prerm 5 "2016-08-16" "Debian Project" "dpkg utilities"
+.SH NAME
+deb\-prerm \- package pre-removal maintainer script
+.
+.SH SYNOPSIS
+prerm
+.
+.SH DESCRIPTION
+A package can perform several pre-removal actions via maintainer
+scripts, by including an executable \fIprerm\fP file in its control
+archive (i.e. \fIDEBIAN/prerm\fP during package creation).
+.PP
+The script can be called in the following ways:
+.TP
+\fIprerm\fP \fBremove\fP
+Before the package is removed.
+.TP
+\fIold-prerm\fP \fBupgrade\fP \fInew-version\fP
+Before an upgrade.
+.TP
+\fInew-prerm\fP \fBfailed-upgrade\fP \fIold-version new-version\fP
+If the above \fBupgrade\fP fails.
+.TP
+\fIprerm\fP \fBdeconfigure in-favour\fP \fInew-package new-version\fP
+.TQ
+    [ \fBremoving\fP \fIold-package old-version\fP ]
+Before package is deconfigured while dependency is replaced due to conflict.
+.TP
+\fIprerm\fP \fBremove in-favour\fP \fInew-package new-version\fP
+Before the package is replaced due to conflict.
+.
+.SH SEE ALSO
+.BR dpkg (1).

man/dpkg.1

@@ -956,10 +956,10 @@ for more information about them:
 .nf
 .IR control " (\fBdeb\-control\fP(5))"
 .IR conffiles " (\fBdeb\-conffiles\fP(5))"
-.I preinst
-.I postinst
-.I prerm
-.I postrm
+.IR preinst " (\fBdeb\-preinst\fP(5))"
+.IR postinst " (\fBdeb\-postinst\fP(5))"
+.IR prerm " (\fBdeb\-prerm\fP(5))"
+.IR postrm " (\fBdeb\-postrm\fP(5))"
 .IR triggers " (\fBdeb\-triggers\fP(5))"
 .fi
 .RE

man/po/po4a.cfg

@@ -52,6 +52,18 @@
 [type:man] deb-symbols.5 $lang:$lang/deb-symbols.5 \
            add_$lang:po/$lang.add
 
+[type:man] deb-postinst.5 $lang:$lang/deb-postinst.5 \
+           add_$lang:po/$lang.add
+
+[type:man] deb-postrm.5 $lang:$lang/deb-postrm.5 \
+           add_$lang:po/$lang.add
+
+[type:man] deb-preinst.5 $lang:$lang/deb-preinst.5 \
+           add_$lang:po/$lang.add
+
+[type:man] deb-prerm.5 $lang:$lang/deb-prerm.5 \
+           add_$lang:po/$lang.add
+
 [type:man] deb-triggers.5 $lang:$lang/deb-triggers.5 \
            add_$lang:po/$lang.add