[pacman-dev] [PATCH] manpage update: add real world examples with full path

[Dave Reisner]

On Tue, Oct 04, 2011 at 03:08:07PM +0200, Nico Schottelius wrote:
> Hello .*,
> 
> This is a resent from the discussion from Mon, 14 Jun 2010 14:26:50 +0200,
> which seems never to get through to get applied.

http://projects.archlinux.org/pacman.git/commit/?id=9ebb59680530

Looks like the pacman portion of this was applied and shipped with the
3.5 release.

> 
> Can you check && apply?
> 
> Cheers,
> 
> Nico
> 
> From: Nico Schottelius <nico at kr.ethz.ch>
> 
> Signed-off-by: Nico Schottelius <nico at kr.ethz.ch>
> ---
>  doc/makepkg.8.txt |   16 ++++++++++++++++
>  doc/pacman.8.txt  |   19 +++++++++++++++++++
>  2 files changed, 35 insertions(+), 0 deletions(-)
> 
> diff --git a/doc/makepkg.8.txt b/doc/makepkg.8.txt
> index a2fdb3f..da8d750 100644
> --- a/doc/makepkg.8.txt
> +++ b/doc/makepkg.8.txt
> @@ -187,6 +187,22 @@ Environment Variables
>  	corresponding value defined in linkman:makepkg.conf[5].
>  
>  
> +Examples
> +--------
> +To create a new package from scratch and let makepkg handle integrity checks:
> +
> +   $ mkdir mypkg
> +   $ cd mypkg
> +   # create PKGBUILD
> +   $ makepkg -g >> PKGBUILD
> +   $ makepkg
> +

If this is the only example we're going to add, I think we're setting a
very poor standard. Checksums should always come from upstream, or else
they don't have much meaning. There was a lot of discussion here (6/10)
with no real constructive outcome other than -- "we're not really sure
we want this in makepkg's manpage":

http://mailman.archlinux.org/pipermail/pacman-dev/2010-June/011088.html

> +Files
> +-----
> +PKGBUILD::
> +	Package build description file in the *current* directory.
> +

We have a whole manpage for this, and its linked in the SEE ALSO section
of makepkg(8). I don't think this is needed. Seems inline with Allan's
comments from above.

> +
>  Configuration
>  -------------
>  See linkman:makepkg.conf[5] for more details on configuring makepkg using the
> diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt
> index 3d14a42..e0314dc 100644
> --- a/doc/pacman.8.txt
> +++ b/doc/pacman.8.txt
> @@ -415,6 +415,25 @@ original=X, current=Y, new=Z::
>  	necessary changes into the original file.
>  
>  
> +Examples
> +--------
> +
> +pacman -Ss ne.hack::
> +	Search for regexp "ne.hack" in package database.
> +
> +pacman -S gpm::
> +	Download and install gpm including dependencies.
> +
> +pacman -U /home/nico/ceofhack-0.6-1-x86_64.pkg.tar.gz::
> +	Install ceofhack from a package file (as genererated by PKGBUILD from AUR).
> +
> +pacman -Syu::
> +	Update package list and upgrade all packages afterwards.
> +
> +pacman -Scc::
> +	Remove *all* packages from cache (-Sc removes only uninstalled ones).
> +
> +

And as I already mentioned, this is in the pacman manpage installed on
your system today.

d