Changeset 11595

Timestamp:

Feb 2, 2007, 2:11:45 PM (19 years ago)

Author:

eugene

Message:

clarify recipe inheritence

File:

• trunk/doc/config/config.tex (modified) (4 diffs)

trunk/doc/config/config.tex

@@ -1 @@
-%%% $Id: config.tex,v 1.6 2007-02-02 04:55:38 price Exp $
+%%% $Id: config.tex,v 1.7 2007-02-03 00:11:45 eugene Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -124 +124 @@
 mean ``look up \code{DIR} in the \code{DATAPATH} to get the
 directory''.
+
+The \code{DATAPATH(METADATA)} entry supplies a list of directories
+which may be used as aliases.  Filenames which have the form
+\code{path://PATH/remainder} will be converted to a UNIX path by
+stripping the \code{path://} component and replacing PATH with its
+value from the DATAPATH list.  This allows the database to be moved to
+a different system (with different directory structure) without having
+to search and replace all paths.
 
 \subsubsection{Database setup}
@@ -1371 +1379 @@
 \subsection{Locations}
 
-Recipes may be specified in a number of locations.  Firstly, they may
-be specified on the command line with the \code{-recipe} option,
-giving a symbolic name and a filename or another symbolic name to link
-to.  In addition, they may be specified in the site configuration and
-the camera configuration under the \code{RECIPES} metadata.  Note that
-the \code{PATH} in the site configuration defines the search
-paths for these files.
+Recipes may be specified in a number of locations.  The recipe files
+are loaded in a sequence, with each new file supplementing the recipes
+already defined.  First, the site-wide list of recipes is loaded.
+Next, if a camera can be identified, the camera-specific recipes are
+loaded.  In both locations, the recipes are identified as named files
+under the \code{RECIPES} metadata.  Note that the \code{PATH(STR)} in
+the site configuration defines the search paths for these files.
+Finally, they may be specified on the command line with the
+\code{-recipe} option, giving a symbolic name and a filename or
+another symbolic name to link to.  In addition, individual recipe
+values may be specified on the command line with one of several
+command-line options.
 
 \subsubsection{Recipe combination}
@@ -1453 +1466 @@
 \end{itemize}
 
+The priority for recipe sources is:
+\begin{enumerate}
+\item Site configuration
+\item Camera configuration
+\item Command-line recipes
+\item Command-line options
+\end{enumerate}
+If multiple recipes have the same name, higher priority entries
+over-write the values specified in the lower-priority entries.  Values
+which are not defined in the higher-priority entries are inherited
+from the lower-priority entries.  This allows the user to override any
+recipe values using the command-line, and to specify default values in
+the site configuration, while also having camera-specific values in
+the camera configurations.  A good practice is for the higher-priority
+recipes files to only supply the entries which are different from the
+default values.  
+
+\begin{verbatim}
+loading sequence is:
+
+* in pmConfigRead->pmConfigReadRecipes(config, PM_RECIPE_SOURCE_SITE | PM_RECIPE_SOURCE_CAMERA):
+
+  config->site:RECIPES:NAME=FILE(STR) -> config->recipes:NAME(MD)
+
+  config->camera:RECIPES:NAME=FILE(STR) -> config->recipes:NAME(MD)
+  (if camera is specified)
+
+* in pmConfigRead->pmConfigLoadRecipeArguments (config):
+
+  config->argv:-recipe:NAME=FILE(STR) -> config->arguments:RECIPES:NAME(MD)
+
+  config->argv:-recipe:NAME=REF(STR) -> config->recipesSource:NAME=REF(STR)
+
+* in pmConfigRead->pmConfigLoadRecipeOptions (config, "-D"):
+
+  config->argv:-D:NAME:KEY=VALUE(STR) -> config->arguments:OPTIONS:NAME(MD)
+
+** file is loaded / camera is identified **
+
+* in pmConfigCameraFormatFromHeader->pmConfigReadRecipes(config, PM_RECIPE_SOURCE_CAMERA | PM_RECIPE_SOURCE_CL):
+
+  config->camera:RECIPES:NAME=FILE(STR) -> config->recipes:NAME(MD)
+
+** at this point, all recipes are loaded as MD in either config->recipes, config->arguments:RECIPES, or config->arguments:OPTIONS
+
+  config->arguments:RECIPES:NAME(MD) -> config->recipes:NAME(MD)
+
+** resolve the symbolic names:
+
+  config->recipesSource:NAME=REF(STR):
+  * if REF is in config->recipes, interpolate: config->recipes:REF(MD) -> config->recipes:NAME(MD)
+  * else if REF is in config->recipes:NAME, interpolate: config->recipes:NAME:REF(MD) -> config->recipes:NAME(MD)
+
+** apply the OPTIONS:
+
+  config->arguments:OPTIONS:NAME(MD) -> config->recipes:NAME(MD)
+
+--
+
+Examples:
+program -recipe PPIMAGE ppImage.config -recipe PPIMAGE PPIMAGE_BIAS
+\end{verbatim}
 
 \subsection{Contents}