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

[Allan McRae]

On 15/09/15 08:42, Andrew Gregory wrote:
> ---
>  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
> 

libalpm-hooks vs alpm-hooks...  I lean towards using libalpm-hooks.
Especially as we already have libalpm(3).

> 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.
> +

There should be a description of what an upgrade is.

> +*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.  

began


> Sync triggers
> +may be extracted as a .pacnew file, leaving the trigger path unmodified.
> +

Does that mean /etc/foo.pacnew will not match a Trigger /etc/foo?  Or
will it match despite the file not being modified?

That section needs to be clearer.

> +include::footer.txt[]
>