[pacman-dev] [PATCH v2 6/7] start hook documentation

[Andrew Gregory]

---
 doc/.gitignore       |   1 +
 doc/Makefile.am      |   4 ++
 doc/alpm-hooks.5.txt | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 112 insertions(+)
 create mode 100644 doc/alpm-hooks.5.txt

diff --git a/doc/.gitignore b/doc/.gitignore
index ad496ce..2eae9e4 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -1,3 +1,4 @@
+alpm-hooks.5
 PKGBUILD.5
 libalpm.3
 makepkg.8
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 60a70b3..7e83dd2 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -4,6 +4,7 @@
 # man_MANS if --enable-asciidoc and/or --enable-doxygen are used.
 
 ASCIIDOC_MANS = \
+	alpm-hooks.5 \
 	pacman.8 \
 	makepkg.8 \
 	makepkg-template.1 \
@@ -20,6 +21,7 @@ ASCIIDOC_MANS = \
 DOXYGEN_MANS = $(wildcard man3/*.3)
 
 HTML_MANPAGES = \
+	alpm-hooks.5 \
 	pacman.8.html \
 	makepkg.8.html \
 	makepkg-template.1.html \
@@ -46,6 +48,7 @@ HTML_DOCS = \
 EXTRA_DIST = \
 	asciidoc.conf \
 	asciidoc-override.css \
+	alpm-hooks.5.txt \
 	pacman.8.txt \
 	makepkg.8.txt \
 	makepkg-template.1.txt \
@@ -147,6 +150,7 @@ $(HTML_OTHER): asciidoc.conf Makefile.am
 %.3.html: ASCIIDOC_OPTS += -d manpage
 
 # Dependency rules
+alpm-hooks.5 alpm-hooks.5.html: alpm-hooks.5.txt
 pacman.8 pacman.8.html: pacman.8.txt
 makepkg.8 makepkg.8.html: makepkg.8.txt
 makepkg-template.1 makepkg-template.1.html: makepkg-template.1.txt
diff --git a/doc/alpm-hooks.5.txt b/doc/alpm-hooks.5.txt
new file mode 100644
index 0000000..36e69c4
--- /dev/null
+++ b/doc/alpm-hooks.5.txt
@@ -0,0 +1,107 @@
+/////
+vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us:
+/////
+alpm-hooks(5)
+=============
+
+NAME
+----
+
+alpm-hooks - alpm hook file format
+
+SYNOPSIS
+--------
+
+ [Trigger] (Required, Repeatable)
+ Operation = Sync|Remove (Required)
+ Type = File|Package (Required)
+ Target = <Path|PkgName> (Required, Repeatable)
+
+ [Action] (Required)
+ When = PreTransaction|PostTransaction (Required)
+ Exec = <Command> (Required)
+ Depends = <PkgName> (Optional)
+ AbortOnFail (Optional, PreTransaction only)
+
+DESCRIPTION
+-----------
+
+libalpm provides the ability to specify hooks to run before or after
+transactions based on the packages and/or files being modified.  Hooks consist
+of a single "[Action]" section describing the action to be run and one or more
+"[Trigger]" section describing which transactions it should be run for.
+
+TRIGGERS
+--------
+
+Hooks must contain at least one "[Trigger]" section that determines which
+transactions will cause the hook to run.  If multiple trigger sections are
+defined the hook will run if the transaction matches *any* of the triggers.
+
+*Operation =* Sync|Remove::
+	Select the type of operation to match targets against.
+
+*Type =* File|Package::
+	Select whether targets are matched against transaction packages or files.
+	See CAVEATS for special notes regarding File triggers.
+
+*Target =* path|package::
+	The file path or package name to match against the active transaction.
+	File paths refer to the files in the package archive; the installation root
+	should *not* be included in the path.  Shell-style glob patterns are
+	allowed. It is possible to invert matches by prepending a file with an
+	exclamation mark. May be specified multiple times. Required.
+
+ACTIONS
+-------
+
+*Exec =* /path/to/executable::
+	Executable to run.  Required.
+
+*When =* PreTransaction|PostTransaction::
+	When to run the hook.  Required.
+
+*Depends =* package::
+	Packages that must be installed for the hook to run. May be specified
+	multiple times.
+
+*AbortOnFail*::
+	Causes the transaction to be aborted if the hook exits non-zero.  Only
+	applies to PreTransaction hooks.
+
+OVERRIDING HOOKS
+----------------
+
+Hooks may be overridden by placing a file with the same name in a higher
+priority hook directory.  Hooks may be disabled by overriding them with
+a symlink to /dev/null.
+
+EXAMPLES
+--------
+
+ # Force disks to sync to prevent data corruption
+
+ [Trigger]
+ Operation = Sync
+ Type = Package
+ Target = *
+
+ [Trigger]
+ Operation = Remove
+ Type = Package
+ Target = *
+
+ [Action]
+ Depends = coreutils
+ When = PostTransaction
+ Exec = /usr/bin/sync
+
+CAVEATS
+-------
+
+There is no way to guarantee that the trigger operation was actually performed
+for file triggers.  Removal triggers will match even if the file did not
+actually exist on the file system when the transaction begin.  Sync triggers
+may be extracted as a .pacnew file, leaving the trigger path unmodified.
+
+include::footer.txt[]
-- 
2.5.2