document package-specs

1 files changed, 18 insertions, 3 deletions

diff --git a/share/man/man7/packages-specs.7 b/share/man/man7/packages-specs.7
index fc0e1670ab7..17420e79b59 100644
--- a/share/man/man7/packages-specs.7
+++ b/share/man/man7/packages-specs.7
@@ -1,4 +1,4 @@
-.\" $OpenBSD: packages-specs.7,v 1.16 2010/11/20 10:05:05 espie Exp $
+.\" $OpenBSD: packages-specs.7,v 1.17 2010/11/26 07:46:31 espie Exp $
 .\"
 .\" Copyright (c) 2001 Marc Espie
 .\"
@@ -24,7 +24,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 20 2010 $
+.Dd $Mdocdate: November 26 2010 $
 .Dt PACKAGES-SPECS 7
 .Os
 .Sh NAME
@@ -146,10 +146,25 @@ after removing any version and flavor requirements.
 .Pp
 Without a
 .Sq pkgspec:
-part, any package with the right stem will do: in effect,
+part, by default, any package with the right stem will do: in effect,
 the pkgspec used is
 .Sq stem-* .
 .Pp
+In
+.Ox 4.9 ,
+the dependent port may override this default, and set
+.Ev PKGSPEC
+to achieve a more restrictive default, for instance,
+.Pa databases/db/v3
+sets the default to 
+.Qq PKGSPEC = db->=3,<4
+to avoid collision with 
+.Pa databases/db/v4 .
+Be extra cautious with this functionality: this tweaks the depends line for
+any including package, thus usually requiring a version bump, and is in
+general only required for very messy cases where several incompatible versions 
+of the same software coexist as packages with the same stem.
+.Pp
 An explicit specification such as
 .Qq png-1.0.7 .
 may be used to ask for a more specific version number.