Clarify the specification for include directive

- Explore more alternative options: XInclude and multiple input files
- Change the reasoning: portability and convenience
  (the performance gain is left implicit)
- Clarify what "load" means: context-specific, implicit selective query
- Clarify the resolution of relative paths
- Allow easy automatic validation
  (each to-be-included file must be valid by itself against the schema)

Currently, the include directive can appear only
in fault-trees, components, model-data, and opsa-mef.
Therefore, wording is changed from "anywhere" to "specific places".

en_us.ascii.add.spl

@@ -123,3 +123,6 @@ LAnguage
 XSD
 REgular
 Schematron
+XInclude
+xmlns
+href

mef/model_organization.rst

@@ -56,10 +56,16 @@ Splitting the Model into Several Files
 ======================================
 
 So far, we have written as if the model fits completely into a single file.
-For even medium size PSA models this assumption not compatible with Quality Control.
+For even medium size PSA models, this assumption is not compatible with Quality Control.
 Moreover, such a monolithic organization of data would be very hard to manage
 when several persons work together on the same model.
 
+One option would be to require tools accept multiple input files
+and treat them as if all the constructs were in one large file.
+Even though this approach is simple,
+(a) the grouping format for multiple input files would be left tool-specific,
+and (b) the mechanism is coarse and not as flexible as the options discussed bellow.
+
 A first way to split the model into several files is to use the XML notion of entities:
 in any XML file, it is possible to declare file entities in the preamble,
 and to include them in the body of the document.
@@ -84,20 +90,52 @@ This mechanism is exemplified below.
 This mechanism, however, has the drawback
 that XML tools have to actually include the files into the document,
 hence, making its manipulation heavier.
+Moreover, the individual files are not valid MEF files but arbitrary XML snippets.
+
+Alternative (W3C Candidate Recommendation) approach is to use XInclude,
+general purpose XML Include,
+which is flexible and powerful enough
+to make our custom specification seem redundant.
+
+.. code-block:: xml
+
+    <?xml version="1.0" ?>
+    <smrf xmlns:xi="http://www.w3.org/2001/XInclude">
+        ...
+        <xi:include href="file1.xml"/>
+        ...
+    </smrf>
 
-The Model Exchange Format proposes another simple mechanism to achieve the same goal:
+The Model Exchange Format proposes another simple mechanism
+to achieve the same goal in a portable and convenient way:
 the tag include.
-This tag can be inserted at any place in a document.
-Its effect is to load the content of the given file into the model.
+This tag can be inserted at specific places in a document.
+Its effect is to load the context-specific content of the given file into the model
+as if the select content were textually included
+(i.e., the included content is evaluated in the context of the including container).
+Moreover, only constructs relevant to the including container
+are selected from the given file, ignoring irrelevant constructs.
+For example, fault trees pick model-data (basic events, etc.) but ignore event trees.
+In other words, the included file is treated as a database.
+
+The following are sufficient requirements
+to make include directives portable and easy to validate:
+
+1. The referenced files to be included shall be valid MEF files by themselves
+   enough to pass automatic validation against the MEF schema.
+2. Relative paths in include directives shall be resolved
+   with respect to the location of the current including file.
 
 .. code-block:: xml
 
     <opsa-mef>
         ...
+        <include file="fault-trees.xml"/>
         <include file="basic-events.xml"/>
         ...
     </opsa-mef>
 
+
 Organization of a Model
 =======================
 

mef/schema/mef.rnc

@@ -9,7 +9,7 @@ reference =
 
 include-directive =
   element include {
-    attribute file { xsd:string }
+    attribute file { xsd:anyURI }
   }
 
 include "model.rnc"

mef/schema/model.rnc

@@ -14,5 +14,5 @@ model =
      | fault-tree-definition
      | substitution-definition
      | CCF-group-definition
-     | include-directive)*,
+     | include-directive)*
   }