- adapted to the code: layouts include scsh's version,

install-lib-version,
- specified the location of pkg-def.scm,
- added acknowledgments.

doc/latex/proposal.tex

@@ -1,4 +1,4 @@
-%% $Id: proposal.tex,v 1.2 2004/02/29 20:00:47 michel-schinz Exp $
+%% $Id: proposal.tex,v 1.3 2004/03/21 16:21:55 michel-schinz Exp $
 
 %% TODO
 %% - clean up permissions mess
@@ -114,6 +114,8 @@ The unpacking directory contains at least the following files:
 \begin{description}
 \item[\file{install-pkg}] a script performing the installation of the
   package,
+\item[\file{pkg-def.scm}] a Scheme file containing the installation
+  procedure for the package (see §~\ref{sec:authoring-packages}),
 \item[\file{README}] a textual file containing a short description of
   the package,
 \item[\file{COPYING}] a textual file containing the license of the
@@ -193,24 +195,34 @@ to a \emph{prefix}, specified at installation time using the
   \file{COPYING} which has to be installed in sub-directory
   \file{license} of the \location{doc} location. If the user chooses
   to use the default layout, which maps \location{doc} to directory
-  \file{<package_full_name>/doc} (see §~\ref{sec:scsh-layout}), and
+  \file{<scsh-version>/<package_full_name>/doc} (see
-  specifies \file{/usr/local/share/scsh/modules} as a prefix, then the
+  §~\ref{sec:scsh-layout}), and specifies
+  \file{/usr/local/share/scsh/modules} as a prefix, then the
   \file{COPYING} file will end up in:
 \[
-\underbrace{\mathtt{/usr/local/share/scsh/modules/}}_{1}%
+\begin{small}
-\underbrace{\mathtt{foo-1.2/doc/}}_{2}%
+\underbrace{\mbox{\texttt{/usr/local/share/scsh/modules/}}}_{1}%
-\underbrace{\mathtt{license/COPYING}}_{3}
+\underbrace{\mbox{\texttt{0.6/foo-1.2/doc/}}}_{2}%
+\underbrace{\mbox{\texttt{license/COPYING}}}_{3}
+\end{small}
 \]
-Part 1 is the prefix, part 2 is the layout's mapping for the
+(provided the user is running scsh v0.6.x) Part 1 is the prefix, part
-\location{doc} location, and part 3 is the file name relative to the
+2 is the layout's mapping for the \location{doc} location, and part 3
-location.
+is the file name relative to the location.
 \end{example}
 
 \subsubsection{Predefined layouts}
 \label{sec:predefined-layouts}
 
 Every installation script comes with a set of predefined layouts which
-serve different aims. They are described below.
+serve different aims. They are described below
+
+The directories to which these layouts map locations often have a name
+which includes the current version of scsh and/or the full name of the
+package. In what follows, the notation \file{<version>} represents the
+printed representation of the first two components of scsh's version
+(e.g. \file{0.6} for scsh v0.6.x). The notation \file{<pkg_fname>}
+represents the \emph{full} name of the package being installed.
 
 \paragraph{The \layout{scsh} layout}
 \label{sec:scsh-layout}
@@ -222,19 +234,18 @@ package being installed. Its name is simply the full name of the
 package in question, and it resides in the \file{prefix} directory.
 
 The \layout{scsh} layout maps locations as given in the following
-table, where \file{<package_full_name>} stands for the full name of
+table:
-the package:
 \begin{center}
   \begin{tabular}{|l|l|}
     \hline
-    \textbf{Location} & \textbf{Directory (relative to prefix)}\\
+    \textbf{Location}      & \textbf{Directory (relative to prefix)} \\
     \hline
-    \location{base}        & \file{<package_full_name>}        \\
+    \location{base}        & \file{<version>/<pkg_fname>}            \\
-    \location{active}      & \file{.}                          \\
+    \location{active}      & \file{<version>}                        \\
-    \location{scheme}      & \file{<package_full_name>/scheme} \\
+    \location{scheme}      & \file{<version>/<pkg_fname>/scheme}     \\
-    \location{lib}         & \file{<package_full_name>/lib}    \\
+    \location{lib}         & \file{<version>/<pkg_fname>/lib}        \\
-    \location{doc}         & \file{<package_full_name>/doc}    \\
+    \location{doc}         & \file{<version>/<pkg_fname>/doc}        \\
-    \location{misc-shared} & \file{<package_full_name>}        \\
+    \location{misc-shared} & \file{<version>/<pkg_fname>}            \\
     \hline
   \end{tabular}
 \end{center}
@@ -253,14 +264,14 @@ Standard (FHS, see \href{http://www.pathname.com/fhs/}%
 \begin{center}
   \begin{tabular}{|l|l|}
     \hline
-    \textbf{Location} & \textbf{Directory (relative to prefix)}\\
+    \textbf{Location}    & \textbf{Directory (relative to prefix)}                \\
     \hline
-    \layout{base}        & \file{share/scsh/modules/<package_full_name>}        \\
+    \layout{base}        & \file{share/scsh-<version>/modules/<pkg_fname>}        \\
-    \layout{active}      & \file{share/scsh/modules}                            \\
+    \layout{active}      & \file{share/scsh-<version>/modules}                    \\
-    \layout{scheme}      & \file{share/scsh/modules/<package_full_name>/scheme} \\
+    \layout{scheme}      & \file{share/scsh-<version>/modules/<pkg_fname>/scheme} \\
-    \layout{lib}         & \file{lib/scsh/modules/<package_full_name>}          \\
+    \layout{lib}         & \file{lib/scsh-<version>/modules/<pkg_fname>}          \\
-    \layout{doc}         & \file{share/doc/<package_full_name>}                 \\
+    \layout{doc}         & \file{share/doc/scsh-<version>/<pkg_fname>}            \\
-    \layout{misc-shared} & \file{share/scsh/modules/<package_full_name>}        \\
+    \layout{misc-shared} & \file{share/scsh-<version>/modules/<pkg_fname>}        \\
     \hline
   \end{tabular}
 \end{center}
@@ -364,15 +375,15 @@ as this forces scsh to search them recursively. This could
   scsh packages according to the \layout{fhs} layout in prefix
   directory \file{/usr/local}. The \location{active} location for
   these packages corresponds to the directory
-  \file{/usr/local/share/scsh/modules}, according to section
+  \file{/usr/local/share/scsh-0.6/modules}, according to section
   \ref{sec:fhs-layout}.
 
   Let's also imagine that there is a user called \texttt{john} on this
   machine, who installs additional scsh packages for himself in his
-  home directory, using \file{/home/john/scsh-packages} as a prefix.
+  home directory, using \file{/home/john/scsh} as a prefix.
   To ease their management, he uses the \layout{scsh} layout. The
   \location{active} location for these packages corresponds to the
-  directory \file{/home/john/scsh-packages}, according to section
+  directory \file{/home/john/scsh/0.6}, according to section
   \ref{sec:scsh-layout}.
 
   In order to be able to use scsh packages installed both by the
@@ -381,7 +392,7 @@ as this forces scsh to search them recursively. This could
   variable.  The value of this variable will therefore be:
   \begin{small}
 \begin{verbatim}
-"/usr/local/share/scsh/modules" "/home/john/scsh-packages"
+"/usr/local/share/scsh-0.6/modules" "/home/john/scsh/0.6"
 \end{verbatim}
   \end{small}
 
@@ -395,6 +406,7 @@ as this forces scsh to search them recursively. This could
 \end{example}
 
 \section{Authoring packages}
+\label{sec:authoring-packages}
 
 Once the Scheme and/or C code for a package has been written, the last
 step in turning it into a standard package as defined by this proposal
@@ -452,13 +464,27 @@ The installation statements typically use functions of the
 installation library in order to install files in their target
 location. The available functions are presented below.
 
-\param{Extensions} is currently used only to specify additional
+\param{Extensions} consists in a list of lists, each one starting with
-command-line arguments, but in the future it could serve other
+a symbol identifying the extension, possibly followed by
-purposes. It consists in a list of lists, each one starting with a
+extension-specific parameters. It is used to specify various
-symbol identifying the extension, followed by extension-specific
+parameters, which are usually optional. Currently, the following
-parameters.
+extensions are defined:
-
 \begin{description}
+\item[install-lib-version] specifies the version of the installation
+  library that this package definition requires. The version is
+  specified as a list composed of \emph{exactly two} integers, giving
+  the major and minor version number of the library. Before installing
+  a package, this version requirement is checked and installation
+  aborts if the installation library does not satisfy it.%
+  \footnote{Version $(i_1\,i_2)$ of the installation library satisfies a
+    requirement $(r_1\,r_2)$ if and only if both major numbers are equal,
+    and the minor number of the installation library is greater or
+    equal to the minor requirement. In other words, iff $i_1 = r_1$
+    and $i_2 \ge r_2$.}%
+  It is strongly recommended that package authors provide this
+  information, as it makes it possible to provide helpful error
+  messages to users.
+
 \item[options] enables the script to define additional command-line
   options. It accepts nine parameters in total, with the last three
   being optional. The description of these parameters follows, in the
@@ -647,4 +673,12 @@ to their final location by the system packaging tools.
 %% (Abstract) location
 %% Package loading script
 
+\section{Acknowledgments}
+\label{sec:acknowledgments}
+
+Discussions with Andreas Bernauer, Anthony Carrico, David Frese,
+Martin Gasbichler, Eric Knauel and Daniel Kobras greatly helped the
+design of this proposal. Mark Sapa started everything by asking for a
+Fink package for sunet and sunterlib.
+
 \end{document}