From 51ad24e7c6eab928eabe4aedeba18946d76363dd Mon Sep 17 00:00:00 2001
From: Ciaran McCreesh <ciaran.mccreesh@googlemail.com>
Date: Wed, 19 Mar 2008 10:22:36 +0000
Subject: Optionally include kdebuild-1 documentation.

kdebuild-1 is a new EAPI requested by the Gentoo KDE project for use in their
overlay. Having documentation of this format is useful for package manager
writers and kdebuild-1 ebuild authors, but we may or may not want to include it
in the PMS copy we'll submit to the Council. So we have options in pms.tex to
enable or disable inclusion -- edit the value of the ENABLE-KDEBUILD boolean as
appropriate (for now it's on by default). We also have an option to show what
PMS looks like both with and without ENABLE-KDEBUILD, by showing both sides of
conditionals in different colours. This is the ENABLE-ALL-OPTIONS boolean,
which is also enabled by default.

Squashed commit of the following:

commit 137e55e3a2712e5b1f9cbb5d168634ca68b2dbe9
Author: Ciaran McCreesh <ciaran.mccreesh@googlemail.com>
Date:   Tue Mar 18 07:24:14 2008 +0000

    Wording tweak

commit dcd912651f6d0bda15631ec3f16a306740decebc
Author: Ciaran McCreesh <ciaran.mccreesh@googlemail.com>
Date:   Tue Mar 18 06:56:25 2008 +0000

    Rewrite the "no magic mkdir" rules.

    The ban on magic mkdir voodoo gets really messy definition-wise if it's put on
    'into', since we don't want it to apply where the package manager is explicit.
    Reword it so that it just bans on explicit utilities.

commit e39c9d23614a37c3cd6f7e336598f27712cd4b0a
Author: Ciaran McCreesh <ciaran.mccreesh@googlemail.com>
Date:   Tue Mar 18 06:22:12 2008 +0000

    Optionally include kdebuild-1 documentation.
---
 names.tex | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 56 insertions(+), 5 deletions(-)

(limited to 'names.tex')

diff --git a/names.tex b/names.tex
index 9e26305..4045b81 100644
--- a/names.tex
+++ b/names.tex
@@ -59,8 +59,15 @@ integer, followed by zero or more dot-prefixed positive integers).
 This may optionally be followed by one of \t{[a-z]} (a lowercase letter).
 
 This may be followed by zero or more of the suffixes \t{\_alpha}, \t{\_beta}, \t{\_pre},
-\t{\_rc} or \t{\_p}, which themselves may be suffixed by an optional integer (if not present,
-this integer is assumed to be zero).
+\t{\_rc} or \t{\_p}, which themselves may be suffixed by an optional integer.
+
+\IFKDEBUILDELSE
+{
+    In ebuilds using EAPIs listed in table~\ref{scm-table} as requiring support for the \t{-scm}
+    suffix, the preceding version syntax may be either replaced or suffixed by a \t{scm} part. If
+    both a ``normal'' version and a \t{scm} part are present, they must be separated by a hyphen.
+}{
+}
 
 This may optionally be followed by the suffix \t{-r} followed immediately by an integer (the
 ``revision number''). If this suffix is not present, it is assumed to be \t{-r0}.
@@ -69,11 +76,38 @@ This may optionally be followed by the suffix \t{-r} followed immediately by an
     ability to ignore versions it doesn't recognise. This should probably remain excluded and replaced
     by a proper solution in future EAPIs.}
 
+\IFKDEBUILDELSE
+{
+    \begin{center}
+    \topcaption{EAPIs requiring \t{scm} support}
+    \tablehead{
+        \hline
+        \multicolumn{1}{c}{\textbf{EAPI}} &
+        \multicolumn{1}{c}{\textbf{Requires \t{scm} support?}} \\
+        \hline
+    }
+    \begin{mpxtabular}{ l l } \label{scm-table}
+    \t{0} & No \\
+    \t{1} & No \\
+    \t{kdebuild-1} & Yes \\
+    \hline
+    \end{mpxtabular}
+    \end{center}
+}{
+}
+
 \section{Version Comparison}
 
 Version specifications are compared component by component, moving from left to right.
 
-The first component of the number part is compared using strict integer comparison.
+\IFKDEBUILDELSE
+{
+    If a version starts with \t{scm}, it orders higher than any version that does not
+    start with \t{scm}.  Otherwise, if neither version starts with \t{scm}, the
+}{
+    The
+}
+first component of the number part is compared using strict integer comparison.
 
 Any subsequent components of the number part are compared as follows:
 
@@ -91,8 +125,25 @@ Letter suffixes are compared alphabetically, with any letter being newer than no
 
 If the letters are equal, suffixes are compared. The ordering is \t{\_alpha} is less than
 \t{\_beta} is less than \t{\_pre} is less than \t{\_rc} is less than no suffix is less than
-\t{\_p}. If a suffix string is equal, the associated integer parts (which default to zero)
-are compared using strict integer comparison.
+\IFKDEBUILDELSE
+{
+    \t{\_p} is less than \t{-scm}.
+}{
+    \t{\_p}.
+}
+If a suffix string is equal, the associated integer parts
+\IFKDEBUILDELSE
+{
+    (except for \t{scm} parts)
+}{}
+are compared using strict integer comparison.  A missing integer part is treated as
+\IFKDEBUILDELSE
+{
+    zero, unless the suffix is directly followed by \t{-scm}, in which case it is treated as being
+    higher than any integer.
+}{
+    zero.
+}
 
 If at this point the two versions are still equal, the revision number is compared. The revision
 number has an optional integer suffix and is compared using strict integer comparison as per the
-- 
cgit v1.2.3-65-gdbad

