[edk2-FdfSpecification PATCH 1/2] Use macros in !include file paths

[Michael Kinney <michael.d.kinney@intel.com>]

https://bugzilla.tianocore.org/show_bug.cgi?id=350

The EBNF already allows !include statements to use
$(MACRO) values in the file path.  This change updates
the description and examples for !include statements
to allow the use of macros and specific environment
variables in !include file paths.

Cc: Liming Gao <liming.gao@intel.com>
Cc: Yonghong Zhu <yonghong.zhu@intel.com>
Cc: Kevin W Shaw <kevin.w.shaw@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Michael Kinney <michael.d.kinney@intel.com>
---
 .../22_flash_description_file_format.md            | 21 +++++++++--------
 3_edk_ii_fdf_file_format/32_fdf_definition.md      | 26 +++++++++++++---------
 2 files changed, 26 insertions(+), 21 deletions(-)

diff --git a/2_fdf_design_discussion/22_flash_description_file_format.md b/2_fdf_design_discussion/22_flash_description_file_format.md
index 9c993f4..67c777e 100644
--- a/2_fdf_design_discussion/22_flash_description_file_format.md
+++ b/2_fdf_design_discussion/22_flash_description_file_format.md
@@ -216,19 +216,18 @@ contain complete sections, or combination of both.
 The argument of this statement is a filename. The file is relative to the
 directory that contains this DSC file, and if not found the tool must attempt
 to find the file relative to paths listed in the system environment variables,
-`$(WORKSPACE)`, `$(PACKAGES_PATH)`, `$(EFI_SOURCE)`, `$(EDK_SOURCE)`,
-`$(ECP_SOURCE)` in the file name is permitted. If the file is not found after
-testing for the possible combinations, the parsing tools must terminate with
-an error.
+`$(WORKSPACE)`, `$(PACKAGES_PATH)`, `$(EFI_SOURCE)`, `$(EDK_SOURCE)`, and
+`$(ECP_SOURCE)`.  If the file is not found after testing for the possible
+combinations, the parsing tools must terminate with an error.
 
-Files specified by `!include` statements may not contain `!include` statements.
-
-Macros, defined in this FDF file or in the DSC file, are not permitted in the
+Macros, defined in this FDF file or in the DSC file, are permitted in the
 path or file name of the !include statement, as these files are included prior
-to processing the file for macros. If the path starts with a "$" character,
-then one of the system environment variables, `$(WORKSPACE)`, `$(EDK_SOURCE)`,
-`$(EFI_SOURCE)`, or `$(ECP_SOURCE)` is being used; only these system
-environment variables are permitted to start the path of the included file.
+to processing the file for macros. The system environment variables,
+`$(WORKSPACE)`, `$(EDK_SOURCE)`, `$(EFI_SOURCE)`, and `$(ECP_SOURCE)` may also
+be used; only these system environment variables are permitted to start the
+path of the included file.
+
+Files specified by `!include` statements may not contain `!include` statements.
 
 Statements in !include files must not break the integrity of the FDF file, the
 included file is read in by tools in the exact position of the file, and is
diff --git a/3_edk_ii_fdf_file_format/32_fdf_definition.md b/3_edk_ii_fdf_file_format/32_fdf_definition.md
index 62e54af..e4e9869 100644
--- a/3_edk_ii_fdf_file_format/32_fdf_definition.md
+++ b/3_edk_ii_fdf_file_format/32_fdf_definition.md
@@ -636,16 +636,20 @@ completely new sections of the same section type. If the included file contains
 new sections, then the section being processed in the Platform FDF file is
 considered to have been terminated.
 
-If the filename is a filename, the tools will look for the file in the same
-directory as the FDF file. If the file is not found, and the directory
-containing this FDF file is not the same directory as the directory containing
-the DSC, the tools must attempt to locate the file in the directory tree that
-contains the DSC file. If the filename starts with a "$", then the system
-environment variable will be used to locate the file. If none of these methods
-find the file, and a directory separator is in the filename, the tools will
-attempt to find the file in a WORKSPACE (or directory listed in the
-PACKAGES_PATH) relative path. If the file cannot be found, the build system
-must exit with an appropriate error message.
+If the `<Filename>` contains "$" characters, then macros defined in the DSC
+file, FDF file, and the system environment variables, `$(WORKSPACE)`,
+`$(EDK_SOURCE)`, `$(EFI_SOURCE)`, and `$(ECP_SOURCE)` are substituted into
+`<Filename>`.
+
+The tools look for `<Filename>` relative to the directory the FDF file resides.
+If the file is not found, and the directory containing this FDF file is not the
+same directory as the directory containing the DSC file, the tools must attempt
+to locate the file relaitive to the directory that contains the DSC file.
+
+If none of these methods find the file, and a directory separator is in
+`<Filename>`, the tools attempt to find the file in a WORKSPACE (or a directory
+listed in the PACKAGES_PATH) relative path. If the file cannot be found, the
+build system must exit with an appropriate error message.
 
 The `!include` file cannot contain additional `!include` statements.
 
@@ -658,4 +662,6 @@ The `!include` file cannot contain additional `!include` statements.
 ```
 !include myPlatform/NvRamDefs.txt
 !include myFeatures.mak
+!include $(WORKSPACE)/PackageDir/Features.dsc
+!include $(MACRO1)/AnotherDir/$(MACRO2)/Features.dsc
 ```
-- 
2.6.3.windows.1