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

[Allan McRae]

On 23/06/11 01:57, Dan McGee wrote:
> 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.
>

I have gone with "prompt" as that seem better.

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

Number sounds fine to me.


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

I suppose that could be easily added.  I am adding it to my TODO list as 
I always attempt to use comma separators.

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

Reworded section:

In addition to packages, groups can be specified as well. For example, if
gnome is a defined package group, then `pacman -S gnome` will provide a
prompt allowing you to select which packages to install from a numbered 
list.
The package selection is specified using a space separated list of package
numbers. Sequential packages may be selected by specifying the first and 
last
package numbers separated by a hyphen (`-`). Excluding packages is 
achieved by
prefixing a number or range of numbers with a 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...
>

Not really...  I think you can only select one provider so it is a bit 
different to the group prompt.  dialog -> prompt change has been made.

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