How does the pkg version syntax work?

The ports collection generates a PKGVERSION from the DISTVERSION or
PORTVERSION provided by the port.  This PKGVERSION is then used to
decide whether one package is newer or older than the other.

However, it seems to be poorly documented.  There does not seem to be
any documentation in the man pages and the source code (pkg_version.c)
gives incomplete and seemingly contradictory information:

 - first it says that components are separated by dots
 - then it gives a regex for what does not separate components,
   but that rege excludes both dots and plus signs, despite these
   separating components as per the other comments.
 - plus signs get special treatment (in the version_cmp function),
   but it is never explained what that special treatment is and how
   it works
 - version_cmp then claims that the code supports versions in a way
   more lenient manner than what portlint enforces.  Yet it does not
   say what portlint enforces and it'll be fun to compute the
   intersection of the checks done by the two tools (and possibly
   the additional checks done by the ports framework)

Given that there are some surprises and that even what is documented
in the code is not really obvious (e.g. words are resolved to their
first letters, but pl and snap get special treatment for some reason),
there should really be authoritative documentation for how this works.

But there does not seem to be any.  Anybody interested in improving the
situation?

Yours,
Robert Clausecker

-- 
()  ascii ribbon campaign - for an 8-bit clean world 
/\  - against html email  - against proprietary attachments