git: 0265532b9d - main - Add documentation of pkg-{pre,post}-[de]install[.lua]

The branch main has been updated by pauamma:

URL: https://cgit.FreeBSD.org/doc/commit/?id=0265532b9d1257477d98b832937ac5d0c774a27b

commit 0265532b9d1257477d98b832937ac5d0c774a27b
Author:     Felix Palmen <[email protected]>
AuthorDate: 2022-08-04 10:56:04 +0000
Commit:     Pau Amma <[email protected]>
CommitDate: 2022-11-13 21:35:51 +0000

    Add documentation of pkg-{pre,post}-[de]install[.lua]
    
    PR: 265476
    
    Reported by: Felix Palmen <[email protected]>
    
    Differential Revision:  https://reviews.freebsd.org/D36769
    
    Reviewed by:    bcr, carlavilla
    
    Approved by:    carlavilla (mentor)
---
 .../books/porters-handbook/pkg-files/_index.adoc   | 43 +++++++++++++++++-----
 1 file changed, 33 insertions(+), 10 deletions(-)

diff --git a/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc b/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc
index 9de27bfe7d..d56bc79d9c 100644
--- a/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc
@@ -223,34 +223,45 @@ Most of the time it is by using `maximum_version` to limit its usage to upgrades
 ====
 
 [[pkg-install]]
-== pkg-install
+== pkg-install, pkg-pre-install and pkg-post-install
 
 If the port needs to execute commands when the binary package is installed with `pkg add` or `pkg install`, use [.filename]#pkg-install#.
-This script will automatically be added to the package.
 It will be run twice by `pkg`, the first time as `${SH} pkg-install ${PKGNAME} PRE-INSTALL` before the package is installed, and the second time as `${SH} pkg-install ${PKGNAME} POST-INSTALL` after it has been installed.
 `$2` can be tested to determine which mode the script is being run in.
 The `PKG_PREFIX` environmental variable will be set to the package installation directory.
 
+If you use [.filename]#pkg-pre-install# or [.filename]#pkg-post-install# instead, the script is only run once, before or after installation of the package.
+You can also use [.filename]#pkg-pre-install.lua# or [.filename]#pkg-post-install.lua# to run a lua script instead of a shell script.
+Lua scripts run by `pkg` provide some extensions and a few restrictions, for these see man:pkg-lua-script[5].
+
+These scripts will automatically be added to the package.
+
 [IMPORTANT]
 ====
-This script is here to help you set up the package so that it is as ready to use as possible.
-It _must not_ be abused to start services, stop services, or run any other commands that will modify the currently running system.
+These scripts are here to help you set up the package so that it is as ready to use as possible.
+They _must not_ be abused to start services, stop services, or run any other commands that will modify the currently running system.
 ====
 
 [[pkg-deinstall]]
-== pkg-deinstall
+== pkg-deinstall, pkg-pre-deinstall and pkg-post-deinstall
 
-This script executes when a package is removed.
+These scripts execute when a package is removed.
 
-This script will be run twice by `pkg delete`.
+The [.filename]#pkg-deinstall# script will be run twice by `pkg delete`.
 The first time as `${SH} pkg-deinstall ${PKGNAME} DEINSTALL` before the port is de-installed and the second time as `${SH} pkg-deinstall ${PKGNAME} POST-DEINSTALL` after the port has been de-installed.
 `$2` can be tested to determine which mode the script is being run in.
-The `PKG_PREFIX` environmental variable will be set to the package installation directory
+The `PKG_PREFIX` environmental variable will be set to the package installation directory.
+
+If you use [.filename]#pkg-pre-deinstall# or [.filename]#pkg-post-deinstall# instead, the script is only run once, before or after removal of the package.
+You can also use [.filename]#pkg-pre-deinstall.lua# or [.filename]#pkg-post-deinstall.lua# to run a lua script instead of a shell script.
+Lua scripts run by `pkg` provide some extensions and a few restrictions, for these see man:pkg-lua-script[5].
+
+These scripts will automatically be added to the package.
 
 [IMPORTANT]
 ====
-This script is here to help you set up the package so that it is as ready to use as possible.
-It _must not_ be abused to start services, stop services, or run any other commands that will modify the currently running system.
+These scripts are here to help you set up the package so that it is as ready to use as possible.
+They _must not_ be abused to start services, stop services, or run any other commands that will modify the currently running system.
 ====
 
 [[pkg-names]]
@@ -278,9 +289,21 @@ Here is a list of variable names and their default values.
 |`PKGINSTALL`
 |`${PKGDIR}/pkg-install`
 
+|`PKGPREINSTALL`
+|`${PKGDIR}/pkg-pre-install`
+
+|`PKGPOSTINSTALL`
+|`${PKGDIR}/pkg-post-install`
+
 |`PKGDEINSTALL`
 |`${PKGDIR}/pkg-deinstall`
 
+|`PKGPREDEINSTALL`
+|`${PKGDIR}/pkg-pre-deinstall`
+
+|`PKGPOSTDEINSTALL`
+|`${PKGDIR}/pkg-post-deinstall`
+
 |`PKGMESSAGE`
 |`${PKGDIR}/pkg-message`
 |===