-X<package> X<module> X<namespace>
-
-=item package
-
-Declares the compilation unit as being in the given namespace. The scope
-of the package declaration is from the declaration itself through the end
-of the enclosing block, file, or eval (the same as the C<my> operator).
-All further unqualified dynamic identifiers will be in this namespace.
-A package statement affects only dynamic variables--including those
-you've used C<local> on--but I<not> lexical variables, which are created
-with C<my>. Typically it would be the first declaration in a file to
-be included by the C<require> or C<use> operator. You can switch into a
-package in more than one place; it merely influences which symbol table
-is used by the compiler for the rest of that block. You can refer to
-variables and filehandles in other packages by prefixing the identifier
-with the package name and a double colon: C<$Package::Variable>.
-If the package name is null, the C<main> package as assumed. That is,
-C<$::sail> is equivalent to C<$main::sail> (as well as to C<$main'sail>,
-still seen in older code).
+
+=item package NAMESPACE VERSION
+X<package> X<module> X<namespace> X<version>
+
+=item package NAMESPACE BLOCK
+
+=item package NAMESPACE VERSION BLOCK
+X<package> X<module> X<namespace> X<version>
+
+Declares the BLOCK or the rest of the compilation unit as being in the
+given namespace. The scope of the package declaration is either the
+supplied code BLOCK or, in the absence of a BLOCK, from the declaration
+itself through the end of current scope (the enclosing block, file, or
+C<eval>). That is, the forms without a BLOCK are operative through the end
+of the current scope, just like the C<my>, C<state>, and C<our> operators.
+All unqualified dynamic identifiers in this scope will be in the given
+namespace, except where overridden by another C<package> declaration or
+when they're one of the special identifiers that qualify into C<main::>,
+like C<STDOUT>, C<ARGV>, C<ENV>, and the punctuation variables.
+
+A package statement affects dynamic variables only, including those
+you've used C<local> on, but I<not> lexical variables, which are created
+with C<my>, C<state>, or C<our>. Typically it would be the first
+declaration in a file included by C<require> or C<use>. You can switch into a
+package in more than one place, since this only determines which default
+symbol table the compiler uses for the rest of that block. You can refer to
+identifiers in other packages than the current one by prefixing the identifier
+with the package name and a double colon, as in C<$SomePack::var>
+or C<ThatPack::INPUT_HANDLE>. If package name is omitted, the C<main>
+package as assumed. That is, C<$::sail> is equivalent to
+C<$main::sail> (as well as to C<$main'sail>, still seen in ancient
+code, mostly from Perl 4).
+
+If VERSION is provided, C<package> sets the C<$VERSION> variable in the given
+namespace to a L<version> object with the VERSION provided. VERSION must be a
+"strict" style version number as defined by the L<version> module: a positive
+decimal number (integer or decimal-fraction) without exponentiation or else a
+dotted-decimal v-string with a leading 'v' character and at least three
+components. You should set C<$VERSION> only once per package.