[pacman-dev] [PATCH] Document group and providers selection

[Dan McGee]

On Wed, Jun 22, 2011 at 3:54 AM, Allan McRae <allan at archlinux.org> wrote:
> The format required for selection of packages within the group selection
> dialog is not entirely obvious, so provide some documentation.
>
> Fixes FS#24134.
>
> Signed-off-by: Allan McRae <allan at archlinux.org>
> ---
maint-worthy, although we'll see if we do another release from there
(probably not).
>
> I am crap at writing documentation so suggestions on how to make this
> clearer are more than welcome.
>
>
>  doc/pacman.8.txt |   12 +++++++++---
>  1 files changed, 9 insertions(+), 3 deletions(-)
>
> diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt
> index 531c992..c11439c 100644
> --- a/doc/pacman.8.txt
> +++ b/doc/pacman.8.txt
> @@ -69,13 +69,19 @@ Operations
>        interprets ">" as redirection to file.)
>  +
>  In addition to packages, groups can be specified as well. For example, if
> -gnome is a defined package group, then `pacman -S gnome` will install every
> -package in the gnome group, as well as the dependencies of those packages.
> +gnome is a defined package group, then `pacman -S gnome` will provide a
> +dialog allowing you to select which packages from that group you wish to
"provide a prompt"? I don't see it as a dialog ala ncurses/gtk.

> +install. The package selection is specified using a space separated list of
> +package identifiers. Sequential packages may be selected by specifying the
"package identifiers" sounds more like names. Perhaps "numbers", or is
that too simplistic?

Maybe just another quick sentence saying "Each package in the group is
identified with a number" or something.

> +first and last package identifiers separated by a hyphen (`-`). Excluding
> +packages is achieved by by prefixing a idetifier or range of identifers
"identifier", spelling in two places here.
:set spell in vim is helpful for these, as a side note. Maybe we
should add a similar bit to the modelines in doc/ as I put in NEWS?

Not really what you're attempting to solve here, but now that it is
documented, I'm surprised we don't treat commas or even semicolons as
valid separators, the same as spaces.

> +with a carrot (`^`).
You probably mean "caret".

>  +
>  Packages that provide other packages are also handled. For example, `pacman -S
>  foo` will first look for a foo package. If foo is not found, packages that
>  provide the same functionality as foo will be searched for. If any package is
> -found, it will be installed.
> +found, it will be installed. A selection dialog is provided if multiple
A selection prompt, similar to the one described fro groups, is provided if...

> +packages providing foo are found.
>  +
>  You can also use `pacman -Su` to upgrade all packages that are out of date. See
>  <<SO,Sync Options>> below. When upgrading, pacman performs version comparison
> --
> 1.7.5.4