[pacman-dev] [PATCH 3/3] docs/pacman.conf: Document SigLevel option

[Allan McRae]

On 29/07/11 10:04, Dan McGee wrote:
> This adds docs for SigLevel, which can exist in both [options] and
> [repository] sections. It also does a bit of reworking of the structure
> of this manpage and adds a labeled list under the repo sections where we
> didn't have one before.
>
> Signed-off-by: Dan McGee<dan at archlinux.org>
> ---
>   doc/pacman.conf.5.txt |   90 ++++++++++++++++++++++++++++++++++++++++++++----
>   1 files changed, 82 insertions(+), 8 deletions(-)
>
> diff --git a/doc/pacman.conf.5.txt b/doc/pacman.conf.5.txt
> index 08fd0e1..cc8c1e4 100644
> --- a/doc/pacman.conf.5.txt
> +++ b/doc/pacman.conf.5.txt
> @@ -156,6 +156,10 @@ Options
>   	packages are only cleaned if not installed locally and not present in any
>   	known sync database.
>
> +*SigLevel =* ...::
> +	Set the default signature verification level. For more information, see
> +	<<SC,Package and Database Signature Checking>>  below.
> +
>   *UseSyslog*::
>   	Log action messages through syslog(). This will insert log entries into
>   	+{localstatedir}/log/messages+ or equivalent.
> @@ -193,27 +197,97 @@ contain a file that lists the servers for that repository.
>
>   --------
>   [core]
> -# use this repository first
> -Server = ftp://ftp.archlinux.org/core/os/arch
> +# use this server first
> +Server = ftp://ftp.archlinux.org/$repo/os/$arch
>   # next use servers as defined in the mirrorlist below
>   Include = {sysconfdir}/pacman.d/mirrorlist
>   --------
>
> +The order of repositories in the configuration files matters; repositories
> +listed first will take precedence over those listed later in the file when
> +packages in two repositories have identical names, regardless of version
> +number.
> +
> +*Include =* path::
> +	Include another config file. This file can include repositories or
> +	general configuration options. Wildcards in the specified paths will get
> +	expanded based on linkman:glob[7] rules.
> +
> +*Server =* url::
> +	A full URL to a location where the database, packages, and signatures (if
> +	available) for this repository can be found.
> ++
>   During parsing, pacman will define the `$repo` variable to the name of the
>   current section. This is often utilized in files specified using the 'Include'
>   directive so all repositories can use the same mirrorfile. pacman also defines
>   the `$arch` variable to the value of `Architecture`, so the same mirrorfile can
>   even be used for different architectures.
>
> +*SigLevel =* ...::
> +	Set the default signature verification level. For more information, see
> +	<<SC,Package and Database Signature Checking>>  below.
> +
> +Package and Database Signature Checking
> +---------------------------------------
> +The 'SigLevel' directive is valid in both the `[options]` and repository
> +sections. If used in `[options]`, it sets a default value for any repository
> +that does not provide the setting.
> +
> +If set to *Never*, no signature checking will take place.
> +If set to *Optional* , signatures will be checked when present, but unsigned
> +databases and packages will also be accepted.
> +If set to *Required*, signatures will be required on all packages and
> +databases.


My only comment here is that the above could go more paragraph style as 
it seems repetitive given it is in bullet point style just below.


> +Alternatively, you can get more fine-grained control by combining some of
> +the options and prefixes described below. All options passed on a single
> +line are processed in left-to-right fashion, where later options override
> +and/or supplement earlier ones.
> +
> +The options are split into two main groups, described below. Terms used such as
> +``marginally trusted'' are terms used by GnuPG, for more information please
> +consult linkman:gpg[1].
> +
> +When to Check::
> +	These options control if and when signature checks should take place.
> +
> +	*Never*;;
> +		All signature checking is suppressed, even if signatures are present.
> +
> +	*Optional* (default);;
> +		Signatures are checked if present; absence of a signature is not an
> +		error. An invalid signature is a fatal error, as is a signature from a
> +		key not in the keyring.
> +
> +	*Required*;;
> +		Signatures are required; absence of a signature or an invalid signature
> +		is a fatal error, as is a signature from a key not in the keyring.
> +
> +What is Allowed::
> +	These options control what signatures are viewed as permissible. Note that
> +	neither of these options allows acceptance of invalid or expired
> +	signatures, or those from revoked keys.
> +
> +	*TrustedOnly* (default);;
> +		If a signature is checked, it must be in the keyring and fully trusted;
> +		marginal trust does not meet this criteria.
> +
> +	*TrustAll*;;
> +		If a signature is checked, it must be in the keyring, but is not
> +		required to be assigned a trust level (e.g., unknown or marginal
> +		trust).
> +
> +Options in both groups can additionally be prefixed with either *Package* or
> +*Database*, which will cause it to only take effect on the specified object
> +type. For example, `PackageTrustAll` would allow marginal and unknown trust
> +level signatures for packages.
> +
> +The built-in default is the following:
> +
>   --------
> -Server = ftp://ftp.archlinux.org/$repo/os/$arch
> +SigLevel = Optional TrustedOnly
>   --------
>
> -The order of repositories in the configuration files matters; repositories
> -listed first will take precedence over those listed later in the file when
> -packages in two repositories have identical names, regardless of version
> -number.
> -
>   Using Your Own Repository
>   -------------------------
>   If you have numerous custom packages of your own, it is often easier to generate