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

[lolilolicon]

On Tue, Oct 4, 2011 at 9:08 PM, Nico Schottelius
<nico-pacman-dev at schottelius.org> 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.
>
> 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
> +
> +Files
> +-----
> +PKGBUILD::
> +       Package build description file in the *current* directory.
> +
> +

This is really redundant- anyone who knows what a PKGBUILD is knows how to
use makepkg.  Users of makepkg are required to read `makepkg --help` and
the man page, after which the example above is just boring.  Also misleading as
`makepkg -g >> PKGBUILD` is not really the right way to do it- the packager
should always first try to obtain checksums from upstream if possible.

Also, fundamentally, why is this workflow an example?  What's so special about
the -g option it's picked out for demonstration?  Just because *you* use it?
That's pretty random, really.

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

Surprisingly this is already in pacman man page...

Again, why no example for -R, for example?  Such examples are doomed
to randomness.

The only reason I think examples are justified is when they actually add
clarification that otherwise can't be delivered.  Take the date(1) man page:

  $ date --date='@2147483647'

gives an example of a DATE STRING, which is explained nowhere else in
the man page.

  $ TZ='America/Los_Angeles' date

demonstrats the effect of TZ environment, which is also not mentioned elsewhere.

On the other hand, the pacman examples above says almost nothing new.  They're
not only random, but also boring.

I vote for removing this completely.

>  Configuration
>  -------------
>  See linkman:pacman.conf[5] for more details on configuring pacman using the
> --
> 1.7.1
>
>
>
>