Index: trunk/doc-rnd/conf/index_user.html
===================================================================
--- trunk/doc-rnd/conf/index_user.html	(revision 2109)
+++ trunk/doc-rnd/conf/index_user.html	(revision 2110)
@@ -70,7 +70,10 @@
 a single integer, string or a single "yes/no" or "on/off" value (e.g.
 the background color or whether polygons are thin-drawn). For scalars
 the rule is simple: the higher priority value wins and all lower priority
-values are discarded when putting the values into the hash.
+values are discarded when putting the values into the hash. More
+details: <a href="scalars.html"> how different roles and priorities
+can be used with scalars.</a>
+
 <p>
 There are some settings that are represented as an array or list of
 values. They are described in a lihata list item ("li:") in the config
@@ -79,4 +82,11 @@
 in each source, just like the prioirty is set. Check out the
 <a href="lists.html">list merging section</a> for more details.
 
-<h2> the override trick </h2>
\ No newline at end of file
+<h3> blind spots </h3>
+At the end the code does need a value for each setting, so in the final
+render (after the hash) every setting must have a value. To avoid blind spots,
+values not initialized, there is a built-in configuration file, compiled into
+the executable. This file is loaded into role <i>CFR_INTERNAL</i>, and has
+the lowest priority. This configuration file contains the default value for
+all settings.
+
Index: trunk/doc-rnd/conf/lists.html
===================================================================
--- trunk/doc-rnd/conf/lists.html	(revision 2109)
+++ trunk/doc-rnd/conf/lists.html	(revision 2110)
@@ -22,4 +22,104 @@
 In practice this means the user can replace, prepend or append ordered lists
 from various sources. A common example is setting the library search paths.
 
-TODO: EXAMPLES
+<h2> examples </h2>
+
+<h3> simple overwrite </h3>
+Config sources (ordered by priority):
+<table border=1>
+	<tr><th> role    <th> priority <th> policy    <th> content
+	<tr><td> system  <td> 200      <td> overwrite <th> A,B,C
+	<tr><td> user    <td> 400      <td> overwrite <th> (not defined)
+	<tr><td> project <td> 600      <td> overwrite <th> D,E
+</table>
+<p>Merge iterations:
+<table border=1>
+	<tr><th> step <th> description         <th> output list after executing this step <th> remarks
+	<tr><td> 0.   <td> reset the output    <td> (empty) <td> &nbsp;
+	<tr><td> 1.   <td> apply <i>system</i> <td> A,B,C   <td> &nbsp;
+	<tr><td> 2.   <td> apply <i>user</i>   <td> A,B,C   <td> "not defined" doesn't mean "empty", so the list is not deleted - no change
+	<tr><td> 3.   <td> apply <i>project</i><td> D,E     <td> replace the original output because of the overwrite policy
+</table>
+<p>Situation: the project is restricted to local footprint libs; this setup
+makes sure no system or user configuration injects external footprint paths.
+
+<h3> empty overwrite </h3>
+Config sources (ordered by priority):
+<table border=1>
+	<tr><th> role    <th> priority <th> policy    <th> content
+	<tr><td> system  <td> 200      <td> overwrite <th> A,B,C
+	<tr><td> user    <td> 400      <td> overwrite <th> (not defined)
+	<tr><td> project <td> 600      <td> overwrite <th> defined to be an empty list
+</table>
+<p>Merge iterations:
+<table border=1>
+	<tr><th> step <th> description         <th> output list after executing this step <th> remarks
+	<tr><td> 0.   <td> reset the output    <td> (empty) <td> &nbsp;
+	<tr><td> 1.   <td> apply <i>system</i> <td> A,B,C   <td> &nbsp;
+	<tr><td> 2.   <td> apply <i>user</i>   <td> A,B,C   <td> "not defined" doesn't mean "empty", so the list is not deleted - no change
+	<tr><td> 3.   <td> apply <i>project</i><td> (empty) <td> replace the original output because of the overwrite policy
+</table>
+
+<h3> prepend </h3>
+Config sources (ordered by priority):
+<table border=1>
+	<tr><th> role    <th> priority <th> policy    <th> content
+	<tr><td> system  <td> 200      <td> overwrite <th> A,B,C
+	<tr><td> user    <td> 400      <td> prepend   <th> (not defined)
+	<tr><td> project <td> 600      <td> prepend   <th> D,E
+</table>
+<p>Merge iterations:
+<table border=1>
+	<tr><th> step <th> description         <th> output list after executing this step <th> remarks
+	<tr><td> 0.   <td> reset the output    <td> (empty) <td> &nbsp;
+	<tr><td> 1.   <td> apply <i>system</i> <td> A,B,C   <td> &nbsp;
+	<tr><td> 2.   <td> apply <i>user</i>   <td> A,B,C   <td> "not defined" doesn't mean "empty", so the list is not deleted - no change
+	<tr><td> 3.   <td> apply <i>project</i><td> D,E,A,B,C <td> &nbsp;
+</table>
+<p>Situation: the project has its own footprint libs with two paths; these
+should be searched before system and user paths, still, system path is also
+kept so stock footprints can be found.
+<p>
+This is better than hardwiring A,B,C in the project's list: A, B and C may
+depend on the installation on a given system. A project file has no idea
+about how the system is installed but it is assumed system installation
+and the system configuration file are consistent.
+
+<h3> append </h3>
+Config sources (ordered by priority):
+<table border=1>
+	<tr><th> role    <th> priority <th> policy    <th> content
+	<tr><td> system  <td> 200      <td> overwrite <th> A,B,C
+	<tr><td> user    <td> 400      <td> append   <th> (not defined)
+	<tr><td> project <td> 600      <td> append   <th> D,E
+</table>
+<p>Merge iterations:
+<table border=1>
+	<tr><th> step <th> description         <th> output list after executing this step <th> remarks
+	<tr><td> 0.   <td> reset the output    <td> (empty) <td> &nbsp;
+	<tr><td> 1.   <td> apply <i>system</i> <td> A,B,C   <td> &nbsp;
+	<tr><td> 2.   <td> apply <i>user</i>   <td> A,B,C   <td> "not defined" doesn't mean "empty", so the list is not deleted - no change
+	<tr><td> 3.   <td> apply <i>project</i><td> A,B,C,D,E <td> &nbsp;
+</table>
+<p>Situation: the project has its own footprint libs with two paths; these
+should be searched after system and user paths. This means the local footprint
+lib has lower priority than the stock footprints. See system-dependent
+installation remarks in the previous point.
+
+
+<h3> prepend+append </h3>
+Config sources (ordered by priority):
+<table border=1>
+	<tr><th> role    <th> priority <th> policy    <th> content
+	<tr><td> system  <td> 200      <td> overwrite <th> A,B,C
+	<tr><td> user    <td> 400      <td> prepend   <th> X,Y,Z
+	<tr><td> project <td> 600      <td> append    <th> D,E
+</table>
+<p>Merge iterations:
+<table border=1>
+	<tr><th> step <th> description         <th> output list after executing this step <th> remarks
+	<tr><td> 0.   <td> reset the output    <td> (empty) <td> &nbsp;
+	<tr><td> 1.   <td> apply <i>system</i> <td> A,B,C   <td> &nbsp;
+	<tr><td> 2.   <td> apply <i>user</i>   <td> X,Y,Z,A,B,C <td> &nbsp;
+	<tr><td> 3.   <td> apply <i>project</i><td> X,Y,Z,A,B,C,D,E <td> &nbsp;
+</table>
Index: trunk/doc-rnd/conf/scalars.html
===================================================================
--- trunk/doc-rnd/conf/scalars.html	(nonexistent)
+++ trunk/doc-rnd/conf/scalars.html	(revision 2110)
@@ -0,0 +1,56 @@
+<html>
+<body>
+<H1> The new config system in pcb-rnd </H1>
+<H2> Scalars </H2>
+
+Scalar settings have only one value after the merge. The only <i>policy</i>
+available is <i>overwrite</i> - this policy is applied regardless of the
+current policy setting.
+
+<h2> examples </h2>
+
+<h3> simple overwrite </h3>
+Config sources:
+<table border=1>
+	<tr><th> role    <th> priority <th> policy    <th> content
+	<tr><td> system  <td> 200      <td> overwrite <th> A
+	<tr><td> user    <td> 400      <td> overwrite <th> (not defined)
+	<tr><td> project <td> 600      <td> overwrite <th> Q
+</table>
+<p>
+Merge iterations:
+<table border=1>
+	<tr><th> step <th> description         <th> output list after executing this step <th> remarks
+	<tr><td> 0.   <td> reset the output    <td> (empty) <td> &nbsp;
+	<tr><td> 1.   <td> apply <i>system</i> <td> A       <td> &nbsp;
+	<tr><td> 2.   <td> apply <i>user</i>   <td> A       <td> "not defined" doesn't mean "empty", so the list is not deleted - no change
+	<tr><td> 3.   <td> apply <i>project</i><td> Q       <td> replace the original output because of the overwrite policy
+</table>
+<p>Situation: system default overriden by a project setting.
+
+<h3> user-forced value </h3>
+Config sources append:
+<table border=1>
+	<tr><th> role    <th> priority <th> policy    <th> content
+	<tr><td> system  <td> 200      <td> overwrite <th> A
+	<tr><td> user    <td> 650      <td> overwrite <th> E
+	<tr><td> project <td> 600      <td> overwrite <th> Q
+</table>
+<p>
+Merge iterations:
+<table border=1>
+	<tr><th> step <th> description         <th> output list after executing this step <th> remarks
+	<tr><td> 0.   <td> reset the output    <td> (empty) <td> &nbsp;
+	<tr><td> 1.   <td> apply <i>system</i> <td> A       <td> &nbsp;
+	<tr><td> 2.   <td> apply <i>project</i><td> Q       <td> &nbsp;
+	<tr><td> 3.   <td> apply <i>user</i>   <td> E       <td> &nbsp;
+</table>
+<p>Situation: user preference enforced: even if the project file would use
+'Q' for the given setting, the user prefers 'E'. This affects runtime
+(the value of the setting after the merge, in other words how pcb-rnd works),
+but does nto change the project configuration. This allows the given user to
+always use 'E' for the given setting while lets other users working on the
+same project use the value set in the project file.
+
+
+