Config protection, metadata.xml, undefined label fixes and makefile tweaks

git-svn-id: http://svn.repogirl.net/pms/trunk@43 a05a4626-2124-0410-b604-e6c5abf33261

7 files changed, 39 insertions, 4 deletions

diff --git a/Makefile b/Makefile
index 0d4598c..7d3b2b0 100644
--- a/Makefile
+++ b/Makefile
@@ -4,7 +4,7 @@ check : pms.pdf
 	xpdf pms.pdf
 
 clean :
-	rm -f *~ *.pdf *.dvi *.log *.aux *.bbl *.blg *.toc *.lol *.loa pdfinfo.tex || true
+	rm -f *~ *.pdf *.dvi *.log *.aux *.bbl *.blg *.toc *.lol *.loa pdfinfo.tex *.out || true
 
 LATEXFILES = $(shell ls *.tex)
 
diff --git a/appendices.tex b/appendices.tex
index 3437e8f..5b21a02 100644
--- a/appendices.tex
+++ b/appendices.tex
@@ -2,3 +2,10 @@
 
 \chapter{metadata.xml}
 \label{metadata-xml}
+
+The \t{metadata.xml} file is used to contain extra package- or category-level information beyond
+what is stored in ebuild metadata. Its exact format is strictly beyond the scope of this document,
+and is described in the DTD file located at \url{http://www.gentoo.org/dtd/metadata.dtd}.
+
+
+% vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :
diff --git a/config-protection.tex b/config-protection.tex
new file mode 100644
index 0000000..9e0957e
--- /dev/null
+++ b/config-protection.tex
@@ -0,0 +1,26 @@
+\chapter{Configuration File Protection}
+\label{config-protect}
+
+The package manager should provide a means to prevent user configuration files from being
+overwritten by any package updates. The profile variables \t{CONFIG\_PROTECT} and
+\t{CONFIG\_PROTECT\_MASK} (section \ref{profile-variables} control the directories for which this
+should be enforced.
+
+In order to ensure interoperability with configuration update tools, the following scheme should be
+used by all package managers when merging any (regular) file:
+
+\begin{enumerate}
+\item If the directory containing the file to be merged is not listed in \t{CONFIG\_PROTECT}, and is
+    not a subdirectory of any such directory, the file is merged normally.
+\item If the directory containing the file to be merged is listed in \t{CONFIG\_PROTECT\_MASK}, or
+    is a subdirectory of such a directory, the file is merged normally.
+\item If no existing file with the intended filename exists, or the existing file has identical
+    content to the one being merged, the file is installed normally.
+\item Otherwise, prepend the filename with \t{.\_cfg0000\_}. If no file with the new name exists,
+    then the file is merged with this name.
+\item Otherwise, increment the number portion (to form \t{.\_cfg0001\_<name>}) and repeat step 4.
+    Continue this process until a usable filename is found.
+\item If 9999 is reached in this way, behaviour is undefined.
+\end{enumerate}
+
+% vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :
diff --git a/ebuild-vars.tex b/ebuild-vars.tex
index 1b72451..8a964c5 100644
--- a/ebuild-vars.tex
+++ b/ebuild-vars.tex
@@ -30,7 +30,7 @@ All ebuilds must define at least the following variables:
     be defined by an eclass.
 \item[LICENSE] The package's license. Each text token must correspond to a tree ``licenses/`` entry
     (see section \ref{licenses-dir}). Use-conditional, any-of and all-of groups are allowed.
-    May be defined by an eclass.
+    May be defined by an eclass. \label{ebuild-var-LICENSE}
 \item[IUSE] The \t{USE} flags used by the ebuild. Historically, \t{USE\_EXPAND} values and \t{ARCH}
     were not included; package managers should support this for backwards compatibility reasons. Ebuilds
     should list only flags used by the ebuild itself. Any eclass that works with \t{USE} flags
diff --git a/glossary.tex b/glossary.tex
index ee73168..5360ed8 100644
--- a/glossary.tex
+++ b/glossary.tex
@@ -8,7 +8,7 @@ be immediately obvious.
 \item[qualified package name] A package name along with its associated category. For example,
     \t{app-editors/vim} is a qualified package name.
 \item[old-style virtual] An old-style virtual is a psuedo-package which exists if it is listed in an
-    ebuild's \t{PROVIDE} variable. See chapter \ref{old-style-virtuals}.
+    ebuild's \t{PROVIDE} variable. See chapter \ref{old-virtuals}.
 \item[new-style virtual] A new-style virtual is a normal package in the \t{virtual} category which
     installs no files and uses its dependency requirements to pull in a `provider'. This is more
     flexible than the old-style virtuals described above, and requires no special package manager
diff --git a/pms.tex b/pms.tex
index 5098973..26dd95e 100644
--- a/pms.tex
+++ b/pms.tex
@@ -5,7 +5,6 @@
 \usepackage{fullpage}
 \usepackage[light]{draftcopy}
 \usepackage{appendix}
-\usepackage{url}
 \usepackage{hyperref}
 \usepackage{algorithm}
 \usepackage{algorithmic}
@@ -63,6 +62,8 @@
 
 \include{ebuild-environment}
 
+\include{config-protection}
+
 \include{glossary}
 
 \include{appendices}
diff --git a/profile-variables.tex b/profile-variables.tex
index 7752e5e..bb18cb1 100644
--- a/profile-variables.tex
+++ b/profile-variables.tex
@@ -1,4 +1,5 @@
 \section{Profile variables}
+\label{profile-variables}
 
 This section documents variables that have special meaning, or special behaviour, when defined in a
 profile's \t{make.defaults} file.