Expand on INCLUDE behavior for 2701

Author: Colin Robertson

docs/build/reference/i-additional-include-directories.md

@@ -6,51 +6,53 @@ f1_keywords: ["VC.Project.VCCLWCECompilerTool.AdditionalIncludeDirectories", "VC
 helpviewer_keywords: ["/I compiler option [C++]", "Additional Include Directories compiler option", "I compiler option [C++]", "-I compiler option [C++]", "set include directories", "include directories, compiler option [C++]"]
 ms.assetid: 3e9add2a-5ed8-4d15-ad79-5b411e313a49
 ---
-# /I (Additional include directories)
+# `/I` (Additional include directories)
 
 Adds a directory to the list of directories searched for include files.
 
 ## Syntax
 
-> **/I**[ ]*directory*
+> **`/I`**[ ]*directory*
 
 ### Arguments
 
 *directory*<br/>
-The directory to be added to the list of directories searched for include files.
+The directory to add to the list of directories searched for include files.
 
 ## Remarks
 
 To add more than one directory, use this option more than once. Directories are searched only until the specified include file is found.
 
-You can use this option with the ([/X (Ignore Standard Include Paths)](x-ignore-standard-include-paths.md)) option.
+You can use this option on the same command line as the ([`/X` (Ignore standard include paths)](x-ignore-standard-include-paths.md)) option.
+
+A [`#include` directive](../../preprocessor/hash-include-directive-c-cpp.md) can be specified in double-quote (or local-first) form, for example, `#include "local.h"`. Or, it can be specified in angle-bracket (or include-path-first) form, for example, `#include <iostream>`.
 
 The compiler searches directories in the following order:
 
-1. If specified using a [#include directive](../../preprocessor/hash-include-directive-c-cpp.md) in double-quote form, it first searches local directories. The search begins in the same directory as the file that contains the **#include** statement. If this fails to find the file, it searches in the directories of the currently opened include files, in the reverse order in which they were opened. The search begins in the directory of the parent include file and continues upward through the directories of any grandparent include files.
+1. If the **`#include`** directive is specified using double-quote form, it first searches local directories. The search begins in the same directory as the file that contains the **`#include`** directive. If this fails to find the file, it searches in the directories of the currently opened include files, in the reverse order in which they were opened. The search begins in the directory of the parent include file and continues upward through the directories of any grandparent include files.
 
-1. If specified using a **#include** directive in angle bracket form, or if the local directory search has failed, it searches directories specified by using the **/I** option, in the order that CL encounters them on the command line.
+1. If specified using a **`#include`** directive in angle bracket form, or if the local directory search has failed, it searches directories specified by using the **`/I`** option, in the order that CL encounters them on the command line.
 
-1. Directories specified in the **INCLUDE** environment variable.
+1. Directories specified in the **`INCLUDE`** environment variable.
 
 ### To set this compiler option in the Visual Studio development environment
 
 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md).
 
 1. Select the **Configuration Properties** > **C/C++** > **General** property page.
 
-1. Modify the **Additional Include Directories** property.
+1. Modify the **Additional Include Directories** property. You can specify more than one directory at a time in this property. Directories must be separated by a semicolon (**`;`**).
 
 ### To set this compiler option programmatically
 
 - See <xref:Microsoft.VisualStudio.VCProjectEngine.VCCLCompilerTool.AdditionalIncludeDirectories%2A>.
 
 ## Example
 
-The following command looks for the include files requested by MAIN.c in the following order: First, if specified by using double-quotes, local files are searched. Next, search continues in the \INCLUDE directory, then in the \MY\INCLUDE directory, and finally in the directories assigned to the INCLUDE environment variable.
+The following command looks for the include files requested by *`main.c`* in the following order: First, if specified by using double-quotes, local files are searched. Next, search continues in the *`\include`* directory, then in the *`\my\include`* directory, and finally in the directories assigned to the **`INCLUDE`** environment variable, in left to right order.
 
-```
-CL /I \INCLUDE /I\MY\INCLUDE MAIN.C
+```cmd
+CL /I \include /I\my\include main.c
 ```
 
 ## See also

docs/preprocessor/hash-include-directive-c-cpp.md

@@ -1,89 +1,88 @@
 ---
 description: "Learn more about: #include directive (C/C++)"
 title: "#include directive (C/C++)"
-ms.date: "08/29/2019"
+ms.date: 01/19/2021
 f1_keywords: ["#include"]
 helpviewer_keywords: ["preprocessor, directives", "#include directive", "include directive (#include)"]
-ms.assetid: 17067dc0-8db1-4f2d-b43e-ec12ecf83238
 ---
-# #include directive (C/C++)
+# `#include` directive (C/C++)
 
-Tells the preprocessor to treat the contents of a specified file as if they appear in the source program at the point where the directive appears.
+Tells the preprocessor to include the contents of a specified file at the point where the directive appears.
 
 ## Syntax
 
-> **#include** "*path-spec*"\
-> **#include** \<*path-spec*>
+> **`#include "`** *path-spec* **`"`**\
+> **`#include <`** *path-spec* **`>`**
 
 ## Remarks
 
-You can organize constant and macro definitions into include files and then use **#include** directives to add them to any source file. Include files are also useful for incorporating declarations of external variables and complex data types. The types may be defined and named only once in an include file created for that purpose.
+You can organize constant and macro definitions into *include files* (also known as *header files*) and then use **`#include`** directives to add them to any source file. Include files are also useful for incorporating declarations of external variables and complex data types. The types may be defined and named only once in an include file created for that purpose.
 
 The *path-spec* is a file name that may optionally be preceded by a directory specification. The file name must name an existing file. The syntax of the *path-spec* depends on the operating system on which the program is compiled.
 
-For information about how to reference assemblies in a C++ application that's compiled by using [/clr](../build/reference/clr-common-language-runtime-compilation.md), see [#using](../preprocessor/hash-using-directive-cpp.md).
+For information about how to reference assemblies in a C++ application that's compiled by using [`/clr`](../build/reference/clr-common-language-runtime-compilation.md), see [`#using` directive](../preprocessor/hash-using-directive-cpp.md).
 
-Both syntax forms cause that directive to be replaced by the entire contents of the specified include file. The difference between the two forms is the order in which the preprocessor searches for header files when the path is incompletely specified. The following table shows the difference between the two syntax forms.
+Both syntax forms cause the **`#include`** directive to be replaced by the entire contents of the specified file. The difference between the two forms is the order of the paths that the preprocessor searches when the path is incompletely specified. The following table shows the difference between the two syntax forms.
 
-|Syntax Form|Action|
-|---|------------|
-|Quoted form|The preprocessor searches for include files in this order:<br/><br/> 1) In the same directory as the file that contains the **#include** statement.<br/><br/> 2) In the directories of the currently opened include files, in the reverse order in which they were opened. The search begins in the directory of the parent include file and continues upward through the directories of any grandparent include files.<br/><br/> 3) Along the path that's specified by each **/I** compiler option.<br/><br/> 4) Along the paths that are specified by the INCLUDE environment variable.|
-|Angle-bracket form|The preprocessor searches for include files in this order:<br/><br/> 1) Along the path that's specified by each **/I** compiler option.<br/><br/> 2) When compiling occurs on the command line, along the paths that are specified by the INCLUDE environment variable.|
+| Syntax Form | Action |
+|--|--|
+| Quoted form | The preprocessor searches for include files in this order:<br/><br/> 1) In the same directory as the file that contains the **`#include`** statement.<br/><br/> 2) In the directories of the currently opened include files, in the reverse order in which they were opened. The search begins in the directory of the parent include file and continues upward through the directories of any grandparent include files.<br/><br/> 3) Along the path that's specified by each **`/I`** compiler option.<br/><br/> 4) Along the paths that are specified by the `INCLUDE` environment variable. |
+| Angle-bracket form | The preprocessor searches for include files in this order:<br/><br/> 1) Along the path that's specified by each **`/I`** compiler option.<br/><br/> 2) When compiling occurs on the command line, along the paths that are specified by the `INCLUDE` environment variable. |
 
 The preprocessor stops searching as soon as it finds a file that has the given name. If you enclose a complete, unambiguous path specification for the include file between double quotation marks (`" "`), the preprocessor searches only that path specification and ignores the standard directories.
 
-If the file name that's enclosed in double quotation marks is an incomplete path specification, the preprocessor first searches the "parent" file's directory. A parent file is the file that contains the **#include** directive. For example, if you include a file named *file2* in a file named *file1*, *file1* is the parent file.
+If the file name that's enclosed in double quotation marks is an incomplete path specification, the preprocessor first searches the *parent* file's directory. A parent file is the file that contains the **`#include`** directive. For example, if you include a file named *file2* in a file named *file1*, *file1* is the parent file.
 
-Include files can be "nested": An **#include** directive can appear in a file that's named by another **#include** directive. For example, *file2* could include *file3*. In this case, *file1* would still be the parent of *file2*, but it would be the "grandparent" of *file3*.
+Include files can be *nested*: An **`#include`** directive can appear in a file that's named by another **`#include`** directive. For example, *file2* could include *file3*. In this case, *file1* would still be the parent of *file2*, but it would be the grandparent of *file3*.
 
-When include files are nested and when compiling occurs on the command line, directory searching begins in the directories of the parent file. Then it proceeds through the directories of any grandparent files. That is, searching begins relative to the directory that contains the source that's currently being processed. If the file isn't found, the search moves to directories that are specified by the [/I (Additional include directories)](../build/reference/i-additional-include-directories.md) compiler option. Finally, the directories that are specified by the INCLUDE environment variable are searched.
+When include files are nested and when compiling occurs on the command line, directory searching begins in the directory of the parent file. Then it proceeds through the directories of any grandparent files. That is, searching begins relative to the directory that contains the source that's currently being processed. If the file isn't found, the search moves to directories that are specified by the [`/I` (Additional include directories)](../build/reference/i-additional-include-directories.md) compiler option. Finally, the directories that are specified by the `INCLUDE` environment variable are searched.
 
-From the Visual Studio development environment, the INCLUDE environment variable is ignored. For information about how to set the directories that are searched for include files and library files, see [VC++ Directories Property Page](../build/reference/vcpp-directories-property-page.md).
+Within the Visual Studio development environment, the `INCLUDE` environment variable is ignored. The values specified in the project properties for include directories are used instead. For more information about how to set the include directories in Visual Studio, see [Include Directories](../build/reference/vcpp-directories-property-page.md#directory-types) and [Additional Include Directories](../build/reference/c-cpp-prop-page.md#additional-include-directories).
 
 This example shows file inclusion by using angle brackets:
 
 ```C
 #include <stdio.h>
 ```
 
-This example adds the contents of the file named STDIO.H to the source program. The angle brackets cause the preprocessor to search the directories that are specified by the INCLUDE environment variable for STDIO.H, after it searches directories that are specified by the **/I** compiler option.
+The example adds the contents of the file named *`stdio.h`* to the source program. The angle brackets cause the preprocessor to search the directories that are specified by the `INCLUDE` environment variable for *`stdio.h`*, after it searches directories that are specified by the **`/I`** compiler option.
 
 The next example shows file inclusion by using the quoted form:
 
 ```C
 #include "defs.h"
 ```
 
-This example adds the contents of the file that's specified by DEFS.H to the source program. The quotation marks mean that the preprocessor first searches the directory that contains the parent source file.
+The example adds the contents of the file that's specified by *`defs.h`* to the source program. The quotation marks mean that the preprocessor first searches the directory that contains the parent source file.
 
-Nesting of include files can continue up to 10 levels. When the nested **#include** is processed, the preprocessor continues to insert the enclosing include file into the original source file.
+Nesting of include files can continue up to 10 levels. When processing of the nested **`#include`** is finished, the preprocessor continues to insert the enclosing parent include file into the original source file.
 
-**Microsoft Specific**
+**Microsoft-specific**
 
-To locate includable source files, the preprocessor first searches the directories that are specified by the **/I** compiler option. If the **/I** option isn't present, or if it fails, the preprocessor uses the INCLUDE environment variable to find any include files within angle brackets. The INCLUDE environment variable and **/I** compiler option can contain multiple paths, separated by semicolons (**;**). If more than one directory appears as part of the **/I** option or within the INCLUDE environment variable, the preprocessor searches them in the order in which they appear.
+To locate the source files to include, the preprocessor first searches the directories specified by the **`/I`** compiler option. If the **`/I`** option isn't present, or if it fails, the preprocessor uses the `INCLUDE` environment variable to find any include files within angle brackets. The `INCLUDE` environment variable and **`/I`** compiler option can contain multiple paths, separated by semicolons (**`;`**). If more than one directory appears as part of the **`/I`** option or within the `INCLUDE` environment variable, the preprocessor searches them in the order in which they appear.
 
 For example, the command
 
 ```cmd
-CL /ID:\MSVC\INCLUDE MYPROG.C
+CL /ID:\msvc\include myprog.c
 ```
 
-causes the preprocessor to search the directory D:\MSVC\INCLUDE\ for include files such as STDIO.H. The commands
+causes the preprocessor to search the directory *`D:\msvc\include\`* for include files such as *`stdio.h`*. The commands
 
 ```cmd
-SET INCLUDE=D:\MSVC\INCLUDE
-CL MYPROG.C
+SET INCLUDE=D:\msvc\include
+CL myprog.c
 ```
 
 have the same effect. If both sets of searches fail, a fatal compiler error is generated.
 
-If the file name is fully specified for an include file that has a path that includes a colon (for example, F:\MSVC\SPECIAL\INCL\TEST.H), the preprocessor follows the path.
+If the file name is fully specified for an include file that has a path that includes a colon (for example, *`F:\MSVC\SPECIAL\INCL\TEST.H`*), the preprocessor follows the path.
 
-For include files that are specified as `#include "path-spec"`, directory searching begins with the directory of the parent file and then proceeds through the directories of any grandparent files. That is, searching begins relative to the directory that contains the source file that contains the **#include** directive that's being processed. If there is no grandparent file and the file has not been found, the search continues as if the file name were enclosed in angle brackets.
+For include files that are specified as `#include "path-spec"`, directory search begins in the directory of the parent file and then proceeds through the directories of any grandparent files. That is, the search begins relative to the directory that contains the source file that's being processed. If there's no grandparent file and the file still isn't found, the search continues as if the file name were enclosed in angle brackets.
 
-**END Microsoft Specific**
+**END Microsoft-specific**
 
 ## See also
 
 [Preprocessor directives](../preprocessor/preprocessor-directives.md)\
-[/I (Additional include directories)](../build/reference/i-additional-include-directories.md)
+[`/I` (Additional include directories)](../build/reference/i-additional-include-directories.md)