[edk2-InfSpecification PATCH] Clarify statement on package ordering

["Laszlo Ersek" <lersek@redhat.com>]

The description of [Packages] sections states,

> Packages must be listed in the order that may be required for specifying
> include path statements for a compiler. For example, the
> MdePkg/MdePkg.dec file must be listed before the
> MdeModulePkg/MdeModulePkg.dec file.

Clarify that the listing order in [Packages] is only relevant for
resolving header file name collisions between packages. Mention that such
collisions are generally not expected. Remove the example about MdePkg and
MdeModulePkg, because both of those are in edk2, and we'd certainly
address a collision between those packages explicitly (e.g., by renaming
one of the subject header files).

Cc: Andrew Fish <afish@apple.com>
Cc: Leif Lindholm <leif@nuviainc.com>
Cc: Michael Kinney <michael.d.kinney@intel.com>
Cc: Pankaj Bansal <pankaj.bansal@oss.nxp.com>
Cc: Philippe Mathieu-Daudé <philmd@redhat.com>
Suggested-by: Leif Lindholm <leif@nuviainc.com>
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
---

Notes:
    (1) This is the one shot I'm willing to take. If it's not accepted,
        someone else will have to work on this. (I only meant to provide
        some wording ideas under Leif's patch; I don't have time for
        multiple iterations on an actual INF spec patch.)
    
    (2) Repo:   https://github.com/lersek/edk2-InfSpecification
        Branch: pkgs_order
    
    (3) Rendered view:
    
        https://lersek.gitbook.io/laszlo-s-fork-of-the-edk-ii-module-information-inf/v/pkgs_order/3_edk_ii_inf_file_format/37_-packages-_sections#summary

 3_edk_ii_inf_file_format/37_[packages]_sections.md | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/3_edk_ii_inf_file_format/37_[packages]_sections.md b/3_edk_ii_inf_file_format/37_[packages]_sections.md
index 17a8d91ec8aa..6f8b8b6dd250 100644
--- a/3_edk_ii_inf_file_format/37_[packages]_sections.md
+++ b/3_edk_ii_inf_file_format/37_[packages]_sections.md
@@ -42,11 +42,16 @@ Defines the `[Packages]` section tag that is used in EDK II module INF files.
 Each entry in this section contains a directory name, forward slash character
 and the name of the DEC file contained in the directory name.
 
-Packages must be listed in the order that may be required for specifying
-include path statements for a compiler. For example, the _MdePkg/MdePkg.dec_
-file must be listed before the `MdeModulePkg/MdeModulePkg.dec` file. If there
-are PCDs listed in the generated "As Built" INF, the packages that declare any
-PCDs must be listed in this section.
+The order in which packages are listed may be relevant. Said order specifies in
+what order include path statements are generated for a compiler. This may help
+resolve header file name collisions between packages (although such collisions
+are normally not expected). For setting specific include path priorities, the
+packages may be listed in matching order in the INF file. Listing a package
+earlier will cause a compiler to consider include paths from that package
+earlier.
+
+If there are PCDs listed in the generated "As Built" INF, the packages that
+declare any PCDs must be listed in this section.
 
 Each package filename must be listed only once per section. Package filenames
 listed in architectural sections are not permitted to be listed in the common
-- 
2.19.1.3.g30247aa5d201