document why substitutions special-case system props

currently needed for files that are included in other files.

not really happy with how this works now, but documenting it
as a starting point.

maybe to force a substitution to resolve from the root we could
start it with a period? ${.this.is.a.root.prop} ?

HOCON.md

@@ -14,7 +14,7 @@ The following features are desirable, to support human usage:
  - ability to refer to another part of the configuration (set a value to
    another value)
  - import/include another configuration file into the current file
- - a mapping to a flat properties list such as Java's System properties
+ - a mapping to a flat properties list such as Java's system properties
  - ability to get values from environment variables
  - ability to write comments
 
@@ -948,7 +948,7 @@ its substitutions.
 
 ### Conventional override by system properties
 
-For an application's config, Java System properties _override_
+For an application's config, Java system properties _override_
 settings found in the configuration file. This supports specifying
 config options on the command line.
 
@@ -961,9 +961,16 @@ properties.
 
 If you merge system properties in to an application's
 configuration as overrides, then falling back to them for
-substitutions won't add anything - they would already be found in
+substitutions isn't important when parsing a toplevel config file
-the configuration. But if you don't merge them in as overrides
+- they would already be found in the configuration.
-then you could fall back to them.
+
+However, there are some cases when system properties fallbacks are
+used. For example, when a config file is parsed as an include, its
+substitutions are relative to the key the file is included
+underneath. In that case, `${user.home}` might become
+`${something.user.home}` and would not match a system property
+override applied to the root of the config tree. However,
+`${user.home}` always falls back to the system property.
 
 ### Substitution fallback to environment variables
 

README.md

@@ -264,7 +264,24 @@ Here are some features that might be nice to add.
  - substitutions with fallbacks; this could be something like
    `${foo.bar,baz,null}` where it would look up `foo.bar`, then
    `baz`, then finally fall back to null. One question is whether
-   entire nested objects would be allowed as fallbacks.
+   entire nested objects would be allowed as fallbacks.  This
+   feature may not really be needed because you can just list the
+   key multiple times instead: `a=null,a=${?baz},a=${?foo.bar}`
+ - improve handling of substitutions in includes. Right now if you
+   have a parent file `a : { include "child.conf" }` and
+   `child.conf` contains a substitution written `${b}`, then
+   `${b}` ends up referring to `${a.b}` (that is, its parent key
+   is prepended to it). The downside of this is that there's no
+   way to refer to toplevel settings from inside `child.conf`, and
+   system properties must be special-case fallbacks for
+   substitutions to allow them to be used from `child.conf`.  If
+   `${b}` in an include always referred to the root `${b}` then
+   substitutions would not need any special system property
+   awareness, but there would be no way to write a file to be
+   included in another file without knowing the parent key the
+   file would be included into. The solution probably involves
+   special syntax for one of "root-relative" or "file-relative",
+   with the regular syntax meaning one or the other.
 
 ## Rationale