improve docs on version numbers

Closes #2309

pkgs/racket-doc/pkg/scribblings/pkg.scrbl

@@ -70,9 +70,15 @@ Each @tech{package} has associated @deftech{package metadata}:
  @item{a @deftech{version} --- a string of the form @nonterm{maj}@litchar{.}@nonterm{min},
                      @nonterm{maj}@litchar{.}@nonterm{min}@litchar{.}@nonterm{sub}, or
                      @nonterm{maj}@litchar{.}@nonterm{min}@litchar{.}@nonterm{sub}@litchar{.}@nonterm{rel},
+                     @margin-note*{The constraints on version numbers are consistent with @racketmodname[version/utils]
+                     and force version numbers to be in a canonical form. For example, a would-be version
+                     string @racket["4.3.0"] must be written instead as @racket["4.3"], @racket["4.3.1.0"]
+                     must be written instead as @racket["4.3.1"], and @racket["4"] must be written as @racket["4.0"].}
                      where @nonterm{maj}, @nonterm{min}, @nonterm{sub}, and @nonterm{rel} are
-                     all canonical decimal representations of natural numbers, @nonterm{min} has no more
+                     all canonical decimal representations of natural numbers, @nonterm{rel} is not @litchar{0},
-                     than two digits, and @nonterm{sub} and @nonterm{rel} has no more than
+                     @nonterm{sub} is not @litchar{0} unless
+                     @nonterm{rel} is supplied, @nonterm{min} has no more
+                     than two digits, and @nonterm{sub} and @nonterm{rel} have no more than
                      three digits. A version is intended to reflect available features of
                      a package, and should not be confused with different releases of
                      a package as indicated by the @tech{checksum}.}

pkgs/racket-doc/version/version.scrbl

@@ -73,40 +73,78 @@ indicates the current state of the current installation:
 
 @defmodule[version/utils]{
   The @racketmodname[version/utils] library provides a few of convenient
-  utilities for dealing with version strings.  Unless explicitly noted,
+  utilities for dealing with version strings.}
-  these functions do not handle legacy versions of Racket.}
 
 @defproc[(valid-version? [v any/c]) boolean?]{
   Returns @racket[#t] if @racket[v] is a valid Racket version
-  string, @racket[#f] otherwise.}
+  string, @racket[#f] otherwise.
+
+  A valid version has one of the following forms:
+
+  @itemlist[
+    @item{@nonterm{maj}@litchar{.}@nonterm{min}}
+    @item{@nonterm{maj}@litchar{.}@nonterm{min}@litchar{.}@nonterm{sub}}
+    @item{@nonterm{maj}@litchar{.}@nonterm{min}@litchar{.}@nonterm{sub}@litchar{.}@nonterm{rel}}
+  ]
+
+  subject to the following constraints:
+
+  @itemlist[
+
+     @item{@nonterm{maj}, @nonterm{min}, @nonterm{sub}, and
+           @nonterm{rel} are all canonical decimal representations of
+           natural numbers (i.e., decimal digits with no leading
+           @litchar{0} unless the number is exactly @litchar{0})}
+
+    @item{@nonterm{rel} is not @litchar{0}}
+
+    @item{@nonterm{sub} is not @litchar{0} unless @nonterm{rel} is included}
+
+    @item{@nonterm{min} has no more than two digits}
+
+    @item{@nonterm{sub} and @nonterm{rel} have no more than three digits}
+
+  ]
+
+  The constraints force version numbers to be in a canonical form. For
+  example, a would-be version string @racket["4.3.0"] must be written
+  instead as @racket["4.3"], @racket["4.3.1.0"] must be written
+  instead as @racket["4.3.1"], and @racket["4"] must be written as
+  @racket["4.0"].}
   
 @defproc[(version->list [str valid-version?])
          (list/c integer? integer? integer? integer?)]{
   Returns a list of four numbers that the given version string
-  represent.  @racket[str] is assumed to be a valid version.}
+  represent.}
 
 @defproc[(version<? [str1 valid-version?] [str2 valid-version?]) boolean?]{
   Returns @racket[#t] if @racket[str1] represents a version that is
-  strictly smaller than @racket[str2], @racket[#f] otherwise.
+  strictly smaller than @racket[str2], @racket[#f] otherwise.}
-  @racket[str1] and @racket[str2] are assumed to be valid versions.}
 
 @defproc[(version<=? [str1 valid-version?] [str2 valid-version?]) boolean?]{
   Returns @racket[#t] if @racket[str1] represents a version that is
-  smaller than or equal to @racket[str2], @racket[#f] otherwise.
+  smaller than or equal to @racket[str2], @racket[#f] otherwise.}
-  @racket[str1] and @racket[str2] are assumed to be valid versions.}
 
 @defproc[(alpha-version? [str valid-version?]) boolean?]{
   Returns @racket[#t] if the version that @racket[str] represents is an
-  alpha version.  @racket[str] is assumed to be a valid version.}
+  alpha version.
+
+  A version number of the form @nonterm{maj}@litchar{.}@nonterm{min},
+  @nonterm{maj}@litchar{.}@nonterm{min}@litchar{.}@nonterm{sub},
+  or @nonterm{maj}@litchar{.}@nonterm{min}@litchar{.}@nonterm{sub}@litchar{.}@nonterm{rel}
+  is an alpha version if @nonterm{min} is @litchar{90} or more,
+  @nonterm{sub} is @litchar{900} or more, or @nonterm{rel} is
+  @litchar{900} or more.}
 
 @defproc[(version->integer [str string?]) (or/c integer? #f)]{
   Converts the version string into an integer.  For version
   @racket["X.YY.ZZZ.WWW"], the result will be @racketvalfont{XYYZZZWWW}.
-  This function works also for legacy Racket versions, by
+  This function works also for legacy Racket versions by
   translating @racket["XYY.ZZZ"] to @racketvalfont{XYYZZZ000}.  The
   resulting integer can thefore be used to conveniently compare any two
-  (valid) version strings.  If the version string is invalid the
+  (valid) version strings. If the version string is invalid as either a
-  resulting value is @racket[#f].
+  regular version string or a legacy version string, the resulting
+  value is @racket[#f].
 
   Note that this is the only function that deals with legacy version
   strings.}