Fix [70f3b23cad]. Doc fix only

doc/InitStubs.3

@@ -15,19 +15,22 @@ Tcl_InitStubs \- initialize the Tcl stubs mechanism
 .sp
 const char *
 \fBTcl_InitStubs\fR(\fIinterp, version, exact\fR)
+.fi
 .SH ARGUMENTS
 .AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
 Tcl interpreter handle.
 .AP "const char" *version in
-A version string consisting of one or more decimal numbers
-separated by dots.
+A version string, indicating which minimal version of Tcl is accepted.
+Normally just \fB"8.6"\fR. Or \fB"8.6-"\fR if both 8.6 and 9.0 are accepted.
 .AP int exact in
-Non-zero means that only the particular version specified by
-\fIversion\fR is acceptable.
-Zero means that versions newer than \fIversion\fR are also
-acceptable as long as they have the same major version number
-as \fIversion\fR.
+1 means that only the particular version specified by
+\fIversion\fR is accepted.
+0 means that versions newer than \fIversion\fR are also
+accepted. If the\fIversion\fR ends with \fB-\fR,
+higher major versions are accepted as well, otherwise
+the major version must be the same as in \fIversion\fR.
+Other bits have no effect.
 .BE
 .SH INTRODUCTION
 .PP
@@ -37,7 +40,7 @@ This provides two significant benefits to Tcl users:
 .IP 1) 5
 Extensions that use the stubs mechanism can be loaded into
 multiple versions of Tcl without being recompiled or
-relinked.
+relinked, as long as the major Tcl version is the same.
 .IP 2) 5
 Extensions that use the stubs mechanism can be dynamically
 loaded into statically-linked Tcl applications.
@@ -76,14 +79,20 @@ more information.
 and ensure that the correct version of Tcl is loaded.  In addition
 to an interpreter handle, it accepts as arguments a version number
 and a Boolean flag indicating whether the extension requires
-an exact version match or not.  If \fIexact\fR is 0, then the
-extension is indicating that newer versions of Tcl are acceptable
-as long as they have the same major version number as \fIversion\fR;
-1 means that only the specified \fIversion\fR is acceptable.
+an exact version match or not.  If \fIexact\fR is 0, then versions
+newer than \fIversion\fR are also accepted. If the\fIversion\fR
+ends with \fB-\fR, higher major versions are accepted as well,
+otherwise the major version must be the same as in \fIversion\fR.
+1 means that only the specified \fIversion\fR is accepted.
+\fIversion\fR can be any construct as described for \fBpackage require\fR
+(\fBPACKAGE\fR manual page in the section \fBREQUIREMENT\fR).
+Multiple requirement strings like with \fBpackage require\fR are not supported.
+
 \fBTcl_InitStubs\fR returns a string containing the actual version
 of Tcl satisfying the request, or NULL if the Tcl version is not
-acceptable, does not support stubs, or any other error condition occurred.
+accepted, does not support stubs, or any other error condition occurred.
 .SH "SEE ALSO"
 Tk_InitStubs
+package
 .SH KEYWORDS
 stubs

doc/package.n

@@ -48,6 +48,7 @@ The following forms are permitted:
 Removes all information about each specified package from this interpreter,
 including information provided by both \fBpackage ifneeded\fR and
 \fBpackage provide\fR.
+.\" METHOD: ifneeded
 .TP
 \fBpackage ifneeded \fIpackage version\fR ?\fIscript\fR?
 .
@@ -70,6 +71,7 @@ If the \fIscript\fR argument is omitted, the current script for
 version \fIversion\fR of package \fIpackage\fR is returned,
 or an empty string if no \fBpackage ifneeded\fR command has
 been invoked for this \fIpackage\fR and \fIversion\fR.
+.\" METHOD: names
 .TP
 \fBpackage names\fR
 .
@@ -78,11 +80,13 @@ interpreter for which a version has been provided (via
 \fBpackage provide\fR) or for which a \fBpackage ifneeded\fR
 script is available.
 The order of elements in the list is arbitrary.
+.\" METHOD: present
 .TP
 \fBpackage present\fR ?\fB\-exact\fR? \fIpackage\fR ?\fIrequirement...\fR?
 .
 This command is equivalent to \fBpackage require\fR except that it
 does not try and load the package if it is not already loaded.
+.\" METHOD: provide
 .TP
 \fBpackage provide \fIpackage \fR?\fIversion\fR?
 .
@@ -96,6 +100,7 @@ If the \fIversion\fR argument is omitted, then the command
 returns the version number that is currently provided, or an
 empty string if no \fBpackage provide\fR command has been
 invoked for \fIpackage\fR in this interpreter.
+.\" METHOD: require
 .TP
 \fBpackage require \fR\fIpackage \fR?\fIrequirement...\fR?
 .
@@ -108,8 +113,8 @@ loaded;  otherwise it generates an error.
 .RS
 .PP
 A suitable version of the package is any version which satisfies at
-least one of the requirements, per the rules of \fBpackage
-vsatisfies\fR. If multiple versions are suitable the implementation
+least one of the requirements as defined in the section \fBREQUIREMENT\fR below.
+If multiple versions are suitable the implementation
 with the highest version is chosen. This last part is additionally
 influenced by the selection mode set with \fBpackage prefer\fR.
 .PP
@@ -148,6 +153,7 @@ package, then the command returns an error.
 This form of the command is used when only the given \fIversion\fR
 of \fIpackage\fR is acceptable to the caller.  This command is
 equivalent to \fBpackage require \fIpackage version\fR-\fIversion\fR.
+.\" METHOD: unknown
 .TP
 \fBpackage unknown \fR?\fIcommand\fR?
 .
@@ -170,90 +176,30 @@ argument, then the current \fBpackage unknown\fR script is returned,
 or an empty string if there is none.
 If \fIcommand\fR is specified as an empty string, then the current
 \fBpackage unknown\fR script is removed, if there is one.
+.\" METHOD: vcompare
 .TP
 \fBpackage vcompare \fIversion1 version2\fR
 .
 Compares the two version numbers given by \fIversion1\fR and \fIversion2\fR.
 Returns -1 if \fIversion1\fR is an earlier version than \fIversion2\fR,
 0 if they are equal, and 1 if \fIversion1\fR is later than \fIversion2\fR.
+.\" METHOD: versions
 .TP
 \fBpackage versions \fIpackage\fR
 .
 Returns a list of all the version numbers of \fIpackage\fR
 for which information has been provided by \fBpackage ifneeded\fR
 commands.
+.\" METHOD: vsatisfies
 .TP
 \fBpackage vsatisfies \fIversion requirement...\fR
 .
 Returns 1 if the \fIversion\fR satisfies at least one of the given
-requirements, and 0 otherwise. Each \fIrequirement\fR is allowed to
-have any of the forms:
-.RS
-.TP
-min
-.
-This form is called
-.QW min-bounded .
-.TP
-min-
-.
-This form is called
-.QW min-unbound .
-.TP
-min-max
-.
-This form is called
-.QW bounded .
-.RE
-.RS
-.PP
-where
-.QW min
-and
-.QW max
-are valid version numbers. The legacy syntax is
-a special case of the extended syntax, keeping backward
-compatibility. Regarding satisfaction the rules are:
-.RE
-.RS
-.IP [1]
-The \fIversion\fR has to pass at least one of the listed
-\fIrequirement\fRs to be satisfactory.
-.IP [2]
-A version satisfies a
-.QW bounded
-requirement when
-.RS
-.IP [a]
-For \fImin\fR equal to the \fImax\fR if, and only if the \fIversion\fR
-is equal to the \fImin\fR.
-.IP [b]
-Otherwise if, and only if the \fIversion\fR is greater than or equal
-to the \fImin\fR, and less than the \fImax\fR, where both \fImin\fR
-and \fImax\fR have been padded internally with
-.QW a0 .
-Note that while the comparison to \fImin\fR is inclusive, the
-comparison to \fImax\fR is exclusive.
-.RE
-.IP [3]
-A
-.QW min-bounded
-requirement is a
-.QW bounded
-requirement in disguise,
-with the \fImax\fR part implicitly specified as the next higher major
-version number of the \fImin\fR part. A version satisfies it per the
-rules above.
-.IP [4]
-A \fIversion\fR satisfies a
-.QW min-unbound
-requirement if, and only if it is greater than or equal to the
-\fImin\fR, where the \fImin\fR has been padded internally with
-.QW a0 .
-There is no constraint to a maximum.
-.RE
+requirements, and 0 otherwise. \fIrequirements\fR are defined in the \fBREQUIREMENT\fR section below.
+.\" METHOD: prefer
 .TP
 \fBpackage prefer \fR?\fBlatest\fR|\fBstable\fR?
+.
 With no arguments, the commands returns either
 .QW latest
 or
@@ -283,8 +229,8 @@ error.
 .PP
 When an interpreter is created, its initial selection mode value is set to
 .QW stable
-unless the environment variable \fBTCL_PKG_PREFER_LATEST\fR
-is set.  If that environment variable is defined (with any value) then
+unless the environment variable \fBTCL_PKG_PREFER_LATEST\fR is set
+(to any value). Otherwise
 the initial (and permanent) selection mode value is set to
 .QW latest .
 .RE
@@ -339,6 +285,66 @@ and \fBpackage provide\fR commands in scripts, and use the procedure
 Once you have done this, packages will be loaded automatically
 in response to \fBpackage require\fR commands.
 See the documentation for \fBpkg_mkIndex\fR for details.
+.SH "REQUIREMENT"
+.PP
+A \fIrequirement\fR string checks, if a compatible version number of a package is present.
+Most commands accept a list of requirement strings where the highest suitable version is matched.
+.PP
+Each \fIrequirement\fR is allowed to have any of the forms:
+.RS
+.IP \fImin\fR
+This form is called
+.QW min-bounded .
+.IP \fImin\fB\-\fR
+This form is called
+.QW min-unbound .
+.IP \fImin\fB\-\fImax\fR
+This form is called
+.QW bounded .
+.PP
+where
+.QW \fImin\fR
+and
+.QW \fImax\fR
+are valid version numbers. The legacy syntax is
+a special case of the extended syntax, keeping backward
+compatibility. Regarding satisfaction the rules are:
+.IP [1]
+The \fIversion\fR has to pass at least one of the listed
+\fIrequirement\fRs to be satisfactory.
+.IP [2]
+A version satisfies a
+.QW bounded
+requirement when
+.RS
+.IP [a]
+For \fImin\fR equal to the \fImax\fR if, and only if the \fIversion\fR
+is equal to the \fImin\fR.
+.IP [b]
+Otherwise if, and only if the \fIversion\fR is greater than or equal
+to the \fImin\fR, and less than the \fImax\fR, where both \fImin\fR
+and \fImax\fR have been padded internally with
+.QW a0 .
+Note that while the comparison to \fImin\fR is inclusive, the
+comparison to \fImax\fR is exclusive.
+.RE
+.IP [3]
+A
+.QW min-bounded
+requirement is a
+.QW bounded
+requirement in disguise,
+with the \fImax\fR part implicitly specified as the next higher major
+version number of the \fImin\fR part. A version satisfies it per the
+rules above.
+.IP [4]
+A \fIversion\fR satisfies a
+.QW min-unbound
+requirement if, and only if it is greater than or equal to the
+\fImin\fR, where the \fImin\fR has been padded internally with
+.QW a0 .
+There is no constraint to a maximum.
+.RE
 .SH EXAMPLES
 .PP
 To state that a Tcl script requires the Tk and http packages, put this