[pacman-dev] [PATCH] doc: Document pkgver() function

[Allan McRae]

On 23/04/13 17:15, William Giokas wrote:
> Originally from Jason St. John's patch, This is a much simplified
> version explaining some basic functions the four vcs's makepkg supports
> can use to get package version information.
> 
> Signed-off-by: William Giokas <1007380 at gmail.com>
> ---

There were a number of other formatting/typo? fixes in that patch that
were good to go.   I guess I can edit it just to include those bits if
Jason does not resubmit.

> 
> I know that Allan didn't like this patch last time it was sent in, and
> neither did I, but I think that this should be documented. I took out the
> two terrible package versions for the git section, and cut it down to just
> the commands used to actually print out the pkgver, not the whole 
> 
>     pkgver() {
>         cd ...
>         foo bar baz
>     }
> 
> which makes a lot more sense and keeps things to a minimum.
> 
>  doc/PKGBUILD.5.txt | 35 +++++++++++++++++++++++++++++++++++
>  1 file changed, 35 insertions(+)
> 
> diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt
> index ea280a0..bb185ea 100644
> --- a/doc/PKGBUILD.5.txt
> +++ b/doc/PKGBUILD.5.txt
> @@ -450,6 +450,41 @@ The source URL is divided into three components:
>  
>  	*svn*;;
>  		revision
> +*pkgver() Function*::
> +	This function allows 'makepkg' to automatically update the package version of
> +	a package using a script. This is meant to be used with VCS packages.

These examples arrive with no introduction.  Add something like "Example
commands for use with the various supported VCS are:"

> +	*Git*::
> +		*Using git tags*;;
> +			Example output: 1.5.1.g123defa
> +
> +			git describe --long | sed 's/-/./'

I am not a fan of this formatting.  Also, won't the ' in there break
formatting.  I think we need a [[source,sh]] block.

Also, note I added "Example commands" above so the we know these are
commands.  I'd put the command first (in the source block) and the
example output after.

> +		*Using the total number of commits (used when there are no tags)*;;
> +			Example output: 0.r6283.g123defa
> +
> +			echo "0.r$(git rev-list --count HEAD).$(git log -1 --format="%h")"
> +
> +	*Subversion*::
> +		Example output: 8546
> +
> +		svnversion | tr -d [A-z]
> +
> +	*Mercurial*::
> +		Example output: 2813.75881cc5391e
> +
> +		hg identify -ni | awk 'BEGIN{OFS=".";} {print $2 $1}'
> +
> +	*Bazaar*::
> +		Example output: 830
> +
> +		bzr revno
> +

Just delete the fallback bit:

> +	*Fallback*::
> +		If no acceptable version information can be extracted from the
> +		repository, use the current date.
> +		Example output: 20130408
> +
> +		date +%Y%m%d
>  
>  Example
>  -------
>