[pacman-dev] [PATCH 1/6] A couple of minor manpage adjustments

[Jakob Gruber]

Dan and Xavier, thanks for the reviews.
Sending the changes as replies + they are also up at 
https://github.com/schuay/pacman-arch/commits/working

On 02/25/2011 03:30 PM, Dan McGee wrote:
> On Mon, Feb 21, 2011 at 1:02 PM, Jakob Gruber<jakob.gruber at gmail.com>  wrote:
>> Signed-off-by: Jakob Gruber<jakob.gruber at gmail.com>
>> ---
>>   doc/pacman.8.txt |   43 ++++++++++++++++++++-----------------------
>>   1 files changed, 20 insertions(+), 23 deletions(-)
>>
>> diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt
>> index 8a94ebc..c309425 100644
>> --- a/doc/pacman.8.txt
>> +++ b/doc/pacman.8.txt
>> @@ -173,15 +173,15 @@ Transaction Options (apply to '-S', '-R' and '-U')
>>   *-p, \--print*::
>>         Only print the targets instead of performing the actual operation (sync,
>>         remove or upgrade). Use '\--print-format' to specify how targets are
>> -       displayed. The default format string is "%l", which displays url with
>> -       '-S', filename with '-U' and pkgname-pkgver with '-R'.
>> +       displayed. The default format string is "%l", which displays urls with
>> +       '-S', filenames with '-U' and pkgname-pkgver with '-R'.
> I prefer URLs as the canonical version of this word- is it broken in a
> lot of places? I think we use URL everywhere on a quick grep.
>
Fixed.

>>   *\--print-format*<'format'>::
>>         Specify a printf-like format to control the output of the '\--print'
>> -       operation. The possible are attributes are : %n for pkgname, %v for pkgver,
>> +       operation. The possible attributes are: %n for pkgname, %v for pkgver,
>>         %l for location, %r for repo and %s for size.
>>
>> -Upgrade Options (apply to 'S' and 'U')[[UO]]
>> +Upgrade Options (apply to '-S' and '-U')[[UO]]
>>   --------------------------------------------
>>   *-f, \--force*::
>>         Bypass file conflict checks and overwrite conflicting files. If the
>> @@ -214,21 +214,20 @@ Upgrade Options (apply to 'S' and 'U')[[UO]]
>>   Query Options[[QO]]
>>   -------------------
>>   *-c, \--changelog*::
>> -       View the ChangeLog of a package. Not every package will provide one but
>> -       it will be shown if available.
>> +       View the ChangeLog of a package if it exists.
>>
>>   *-d, \--deps*::
>>         Restrict or filter output to packages installed as dependencies. This
>> -       option can be combined with '-t' for listing real orphans- packages that
>> +       option can be combined with '-t' for listing real orphans - packages that
>>         were installed as dependencies but are no longer required by any
>>         installed package. ('-Qdt' is equivalent to the pacman 3.0.X '-Qe'
>>         option.)
>>
>>   *-e, \--explicit*::
>> -       Restrict or filter output to packages explicitly installed. This option
>> -       can be combined with '-t' to list top-level packages- those packages
>> -       that were explicitly installed but are not required by any other
>> -       package. ('-Qet' is equivalent to the pacman 2.9.X '-Qe' option.)
>> +       Restrict or filter output to explicitly installed packages. This option
>> +       can be combined with '-t' to list explicitly installed packages which
>> +       are not required by any other package. ('-Qet' is equivalent to the
>> +       pacman 2.9.X '-Qe' option.)
> I'd say we can even dump the 2.9.X and 3.0.X notices here in these two
> messages- it has been a while and this will just confuse most users
> reading up on these options.
>
Right, done.

>>   *-g, \--groups*::
>>         Display all packages that are members of a named group. If a name is not
>> @@ -255,8 +254,8 @@ Query Options[[QO]]
>>         and installed with '\--upgrade'.
>>
>>   *-o, \--owns*<'file'>::
>> -       Search for the package that owns file. The path can be relative or
>> -       absolute.
>> +       Search for the package that owns the specified file. The path can be
>> +       relative or absolute.
> This is really file(s)- not sure if we can adjust things to be clearer
> about that. The text is easy, the first line opt description might be
> trickier.
>
I modified the text and left the oneliner as is.

>>   *-p, \--file*::
>>         Signifies that the package supplied on the command line is a file and
>> @@ -274,7 +273,7 @@ Query Options[[QO]]
>>         rather than names and versions.
>>
>>   *-s, \--search*<'regexp'>::
>> -       This will search each locally-installed package for names or
>> +       This will search each locally installed package for names or
> Kill the "this will" if you are changing this line anyway. And can you
> point at a grammar book that says why the hyphen should go away? It
> seems like this should have a hyphen to me.
>
Reverted to "locally-installed" and removed "This will".

>>         descriptions that match `regexp`. When you include multiple search
>>         terms, only packages with descriptions matching ALL of those terms will
>>         be returned.
>> @@ -298,9 +297,8 @@ Remove Options[[RO]]
>>         with care since it can remove many potentially needed packages.
>>
>>   *-n, \--nosave*::
>> -       Instructs pacman to ignore file backup designations. Normally, when a
>> -       file is removed from the system the database is checked to see if the
>> -       file should be renamed with a ``.pacsave'' extension.
>> +       Delete backup files instead of renaming them with a ``.pacsave''
>> +       extension.
> I think you've oversimplified this. Backup files are not made if you
> never changed the file, and even though the original text here was
> perhaps a bit unwieldy, it hinted at this. Please confirm this
> behavior (look at some pactests?) and adjust the text accordingly.
>
Reverted this change.

>>   *-s, \--recursive*::
>>         Remove each target specified including all of their dependencies, provided
>> @@ -310,7 +308,7 @@ Remove Options[[RO]]
>>         orphans. If you want to omit condition (B), pass this option twice.
>>
>>   *-u, \--unneeded*::
>> -       Removes the targets that are not required by any other packages.
>> +       Removes targets that are not required by any other packages.
>>         This is mostly useful when removing a group without using the '-c' option,
>>         to avoid breaking any dependencies.
>>
>> @@ -372,18 +370,17 @@ linkman:pacman.conf[5].
>>         the same operation.
>>
>>   *-w, \--downloadonly*::
>> -       Retrieve all packages from the server, but do not install/upgrade
>> -       anything.
>> +       Retrieve all packages from the server, but do not install/upgrade anything.
>>
>>   *-y, \--refresh*::
>>         Download a fresh copy of the master package list from the server(s)
>>         defined in linkman:pacman.conf[5]. This should typically be used each time
>>         you use '\--sysupgrade' or '-u'. Passing two '\--refresh' or '-y' flags
>> -       will force a refresh of all package lists even if they are thought to be up
>> +       will force a refresh of all package lists even if they appear to be up
>>         to date.
>>
>>   *\--needed*::
>> -       Don't reinstall the targets that are already up-to-date.
>> +       Don't reinstall the targets that are already up to date.
>>
>>
>>   Handling Config Files[[HCF]]
>> @@ -396,7 +393,7 @@ actual file existing on the filesystem. After comparing these 3 hashes, the
>>   follow scenarios can result:
>>
>>   original=X, current=X, new=X::
>> -       All three files are the same, so overwrites are not an issue Install the
>> +       All three files are the same, so overwrites are not an issue. Install the
>>         new file.
>>
>>   original=X, current=X, new=Y::
>> --
>> 1.7.4.1
>>
>>
>>