# HG changeset patch
# User Carnë Draug <carandraug@octave.org>
# Date 1460571801 -3600
# Node ID 1fff60b89786c0770d65566d4589ea7c305dba43
# Parent  32cd60419b618ecbab701a8a69b75b1b17981019
pkg: add comments explaining valid character set for version string.

diff -r 32cd60419b61 -r 1fff60b89786 scripts/pkg/private/get_description.m
--- a/scripts/pkg/private/get_description.m	Tue Apr 12 19:11:27 2016 +0100
+++ b/scripts/pkg/private/get_description.m	Wed Apr 13 19:23:21 2016 +0100
@@ -132,8 +132,19 @@
   ## We are limiting ourselves to this set of characters because the
   ## version will appear on the filepath.  The portable character, according
   ## to http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_278
-  ## is [A-Za-z0-9\.\_\-].  However, this is very limited.  We expand this
-  ## set with the characters supported by Debian with the exception of ":"
-  ## (we do not support ":" (colon) because that's the Octave path separator.
+  ## is [A-Za-z0-9\.\_\-].  However, this is very limited.  We specially
+  ## want to support a "+" so we can support "pkgname-2.1.0+" during
+  ## development.  So we use Debian's character set for version strings
+  ## https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version
+  ## with the exception of ":" (colon) because that's the PATH separator.
+  ##
+  ## Debian does not include "_" because it is used to separate the name,
+  ## version, and arch in their deb files.  While the actual filenames are
+  ## never parsed to get that information, it is important to have a unique
+  ## separator character to prevent filename clashes.  For example, if we
+  ## used hyhen as separator, "signal-2-1-rc1" could be "signal-2" version
+  ## "1-rc1" or "signal" version "2-1-rc1".  A package file for both must be
+  ## able to co-exist in the same directory, e.g., during package install or
+  ## in a flat level package repository.
   valid = numel (regexp (str, '[^0-9a-zA-Z\.\+\-\~]')) == 0;
 endfunction