[edk2-DscSpecification PATCH] Use macros in !include file paths

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

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

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>
---
 2_dsc_overview/22_build_description_file_format.md    | 19 +++++++++----------
 .../33_platform_dsc_definition.md                     | 19 ++++++++++++-------
 README.md                                             |  3 ++-
 3 files changed, 23 insertions(+), 18 deletions(-)

diff --git a/2_dsc_overview/22_build_description_file_format.md b/2_dsc_overview/22_build_description_file_format.md
index ebe4cca..d32c9b0 100644
--- a/2_dsc_overview/22_build_description_file_format.md
+++ b/2_dsc_overview/22_build_description_file_format.md
@@ -230,9 +230,15 @@ definition, 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 the paths listed in the system environment
-variables, `$(WORKSPACE)`, `$(EFI_SOURCE)`, `$(EDK_SOURCE)`, `$(ECP_SOURCE)` in
-the file name is permitted. If the file is still not found, the parsing tools
-must terminate with an error.
+variables `$(WORKSPACE)`, `$(EFI_SOURCE)`, `$(EDK_SOURCE)`, and
+`$(ECP_SOURCE)`. If the file is still not found, the parsing tools must
+terminate with an error.
+
+Macros, defined in this 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. 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.
 
@@ -241,13 +247,6 @@ the included file is read in by tools in the exact position of the file, and is
 functionally equivalent of copying the contents of the included file and
 inserting (paste) the content into the DSC file.
 
-Macros, defined in this file, are not 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.
-
 The following examples show the valid usage of the `!include` statement.
 
 ```ini
diff --git a/3_edk_ii_dsc_file_format/33_platform_dsc_definition.md b/3_edk_ii_dsc_file_format/33_platform_dsc_definition.md
index 8119ee4..1ed3f7e 100644
--- a/3_edk_ii_dsc_file_format/33_platform_dsc_definition.md
+++ b/3_edk_ii_dsc_file_format/33_platform_dsc_definition.md
@@ -655,18 +655,21 @@ section that the `!include` statement resides, or it may contain completely new
 sections. If the included file starts with a section header, then the section
 being processed in the Platform DSC file is considered to have been terminated.
 
+If the `<Filename>` contains "$" characters, then macros defined in the DSC
+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 DSC file resides.
+If the file is not found, 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.
 
 Statements in the include file are permitted to override previous definitions
 as well as to define new entries.
 
-If the filename is a filename, the tools will look for the file in the same
-directory as the DSC file. If the filename starts with a "$", then the system
-environment variable will be used to locate the file. If neither of these
-methods find the file, and a directory separator is in the filename, the tools
-will attempt to find the file in an EDK II Package . If the file cannot be
-found, the build system must exit with an appropriate error message.
-
 #### Prototype
 
 `<IncludeStatement> ::= <TS> "!include" <MTS> <Filename> <EOL>`
@@ -676,6 +679,8 @@ found, the build system must exit with an appropriate error message.
 ```
 !include MyPlatformPkg/feature_pcds.mak
 !include MyFeatures.mak
+!include $(WORKSPACE)/PackageDir/Features.dsc
+!include $(MACRO1)/AnotherDir/$(MACRO2)/Features.dsc
 ```
 
 **********
diff --git a/README.md b/README.md
index 7a87ccf..64bf2b7 100644
--- a/README.md
+++ b/README.md
@@ -176,4 +176,5 @@ Copyright (c) 2006-2017, Intel Corporation. All rights reserved.
 |            | Update the DSC_SPECIFICATION version to 0x0001001A                                                                                                                                                                                                                                           |                |
 |            | Revised WORKSPACE wording for updated build system that can handle packages located outside of the WORKSPACE directory tree (refer to the TianoCore.org/ EDKII website for additional instructions on setting up a development environment).                                                 |                |
 |            | Added new system environment variables used by the build system.                                                                                                                                                                                                                             |                |
-| 1.27       | Convert to GitBooks                                                                                                                                                                                                                                                                          | March 2017     |
+| 1.27       | Convert to GitBooks                                                                                                                                                                                                                                                                          | April 2017     |
+|            | [#351](https://bugzilla.tianocore.org/show_bug.cgi?id=351) [DSC Spec] Extend macro usage in the !include statement                                                                                                                                                                           |                |
-- 
2.6.3.windows.1