edits

TylerMSFT · TylerMSFT · commit 9e1b285910eb · 2024-01-26T16:09:35.000-08:00
diff --git a/docs/cpp/tutorial-import-stl-named-module.md b/docs/cpp/tutorial-import-stl-named-module.md
@@ -55,17 +55,17 @@ The following examples demonstrate how to consume the standard library as a modu
 
 The statement `import std;` or `import std.compat;` imports the standard library into your application. But first, you must compile the standard library named modules into binary form. The following steps demonstrate how.
 
-### Example: `std`
+### Example: How to build and import `std`
 
 1. Open a x86 Native Tools Command Prompt for VS: from the Windows **Start** menu, type *x86 native* and the prompt should appear in the list of apps. Ensure that the prompt is for Visual Studio 2022 version 17.5 or above. You'll get errors if you use the wrong version of the prompt. The examples used in this tutorial are for the CMD shell.
-1. Create a directory, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors during compilation such as not being able to open the output file `std.ifc`.
+1. Create a directory, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors during compilation.
 1. Compile the `std` named module with the following command:
 
     ```cmd
     cl /std:c++latest /EHsc /nologo /W4 /c "%VCToolsInstallDir%\modules\std.ixx"
     ```
 
-    If you get errors, ensure that you're using the correct version of the command prompt. If you're still having issues, please file a bug at [Visual Studio Developer Community](https://developercommunity.visualstudio.com/home).
+    If you get errors, ensure that you're using the correct version of the command prompt.
 
     Compile the `std` named module using the same compiler settings that you intend to use with the code that imports the built module. If you have a multi-project solution, you can compile the standard library named module once, and then refer to it from all of your projects by using the [`/reference`](../build/reference/module-reference.md) compiler option.
 
@@ -83,8 +83,8 @@ The statement `import std;` or `import std.compat;` imports the standard library
     | [`/c`](../build/reference/c-compile-without-linking.md) | Compile without linking, because we're just building the binary named module interface at this point. |
 
     You can control the object file name and the named module interface file name with the following switches:
-    - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo "somethingelse.obj"`. By default, the compiler uses the same name as the module source file (`.ixx`) you are compiling. In the example, the output name is `std.obj` by default because we're compiling the module file `std.ixx`.
-    - [`/ifcOutput`](../build/reference/ifc-output.md) sets the name of the named module interface file (`.ifc`). For example, `/ifcOutput "somethingelse.ifc"`. By default, the compiler uses the same name as the module source file (`.ixx`) you are compiling. In the example, the generated `ifc` file is `std.ifc` by default because we're compiling the module file `std.ixx`.
+    - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo "somethingelse.obj"`. By default, the compiler uses the same name for the object file as the module source file (`.ixx`) you're compiling. In the example, the output name is `std.obj` by default because we're compiling the module file `std.ixx`.
+    - [`/ifcOutput`](../build/reference/ifc-output.md) sets the name of the named module interface file (`.ifc`). For example, `/ifcOutput "somethingelse.ifc"`. By default, the compiler uses the same name for the module interface file (`.ifc`) as the module source file (`.ixx`) you're compiling. In the example, the generated `ifc` file is `std.ifc` by default because we're compiling the module file `std.ixx`.
 
 1. Importing the `std` library you just built by first creating a file named `importExample.cpp` with the following content:
 
@@ -113,11 +113,13 @@ The statement `import std;` or `import std.compat;` imports the standard library
     link importExample.obj std.obj
     ```
 
-    It isn't necessary to specify `/reference "std=std.ifc"` on the command line in this example because the compiler automatically looks for the `.ifc` file matching the module name specified by the `import` statement. When the compiler encounters `import std;`, it can find `std.ifc` if it is located in the same directory as the source code. If the `.ifc` file is in a different directory than the source code, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it.
+    It isn't necessary to specify `/reference "std=std.ifc"` on the command line in this example because the compiler automatically looks for the `.ifc` file matching the module name specified by the `import` statement. When the compiler encounters `import std;` it can find `std.ifc` if it is located in the same directory as the source code. If the `.ifc` file is in a different directory than the source code, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it.
 
-    In this example, compiling your source code and linking the module's implementation into your application are separate steps. They don't have to be. You could have used `cl /std:c++latest /EHsc /nologo /W4 /reference "std=std.ifc" importExample.cpp std.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects, in your build's link step.
+    In this example, compiling your source code and linking the module's implementation into your application are separate steps. They don't have to be. You could use `cl /std:c++latest /EHsc /nologo /W4 /reference "std=std.ifc" importExample.cpp std.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects, in your build's link step.
 
-    If you're building a single project, you can combine the steps of building the `std` standard library named module and the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` to the command line. Make sure to put it before any `.cpp` files that consume it. By default, the output executable's name is taken from the first input file. Use the `/Fe` compiler option to specify the output file name you want. This tutorial shows compiling the `std` named module as a separate step because you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects. But it may be convenient to build everything together, as shown by this command line:
+    If you're building a single project, you can combine the steps of building the `std` standard library named module and the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` to the command line. Put it before any `.cpp` files that consume the `std` module.
+
+    By default, the output executable's name is taken from the first input file. Use the `/Fe` compiler option to specify the output file name you want. This tutorial shows compiling the `std` named module as a separate step because you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects. But it may be convenient to build everything together, as shown by this command line:
 
     ```cmd
     cl /FeimportExample /std:c++latest /EHsc /nologo /W4 "%VCToolsInstallDir%\modules\std.ixx" importExample.cpp
@@ -130,20 +132,18 @@ The statement `import std;` or `import std.compat;` imports the standard library
     555
     ```
 
-    The key command-line switches in this example are the same as the previous example, except that the `/c` switch isn't used.
-
 ## Import the standard library and global C functions with `std.compat`
 
 The C++ standard library includes the ISO C standard library. The `std.compat` module provides all of the functionality of the `std` module like `std::vector`, `std::cout`, `std::printf`, `std::scanf`, and so on. But it also provides the global namespace versions of these functions such as `::printf`, `::scanf`, `::fopen`, `::size_t`, and so on.
 
 The `std.compat` named module is a compatibility layer provided to ease migrating existing code that refers to C runtime functions in the global namespace. If you want to avoid adding names to the global namespace, use `import std;`. If you need to ease migrating a codebase that uses many unqualified (global namespace) C runtime functions, use `import std.compat;`. This provides the global namespace C runtime names so that you don't have to qualify all the global names with `std::`. If you don't have any existing code that uses the global namespace C runtime functions, then you don't need to use `import std.compat;`. If you only call a few C runtime functions in your code, it may be better to use `import std;` and qualify the few global namespace C runtime names that need it with `std::`. For example, `std::printf()`. If you see an error like `error C3861: 'printf': identifier not found` when you try to compile your code, consider using `import std.compat;` to import the global namespace C runtime functions.
 
-### Example: `std.compat`
+### Example: How to build and import `std.compat`
 
 Before you can use `import std.compat;` you must compile the module interface file found in source code form in `std.compat.ixx`. Visual Studio ships the source code for the module so that you can compile the module using the compiler settings that match your project. The steps are similar to for building the `std` named module. The `std` named module is built first because `std.compat` depends on it:
 
 1. Open a Native Tools Command Prompt for VS: from the Windows **Start** menu, type *x86 native* and the prompt should appear in the list of apps. Ensure that the prompt is for Visual Studio 2022 version 17.5 or above. You'll get compiler errors if you use the wrong version of the prompt.
-1. Create a directory to try this example, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors such as not being able to open the output file `std.ifc`.
+1. Create a directory to try this example, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors.
 1. Compile the `std` and `std.compat` named modules with the following command:
 
     ```cmd
@@ -152,17 +152,17 @@ Before you can use `import std.compat;` you must compile the module interface fi
 
     You should compile `std` and `std.compat` using the same compiler settings that you intend to use with the code that imports them. If you have a multi-project solution, you can compile them once, and then refer to them from all of your projects using the [`/reference`](../build/reference/module-reference.md) compiler option.
 
-    If you get errors, ensure that you're using the correct version of the command prompt. If you're still having issues, please file a bug at [Visual Studio Developer Community](https://developercommunity.visualstudio.com/home).
+    If you get errors, ensure that you're using the correct version of the command prompt.
 
     The compiler outputs four files from the previous two steps:
     - `std.ifc` is the compiled binary named module interface that the compiler consults to process the `import std;` statement. The compiler also consults `std.ifc` to process `import std.compat;` because `std.compat` builds on `std`. This is a compile-time only artifact. It doesn't ship with your application.
     - `std.obj` contains the implementation of the standard library.
     - `std.compat.ifc` is the compiled binary named module interface that the compiler consults to process the `import std.compat;` statement. This is a compile-time only artifact. It doesn't ship with your application.
     - `std.compat.obj` contains implementation. However, most of the implementation is provided by `std.obj`. Add `std.obj` to the command line when you compile the sample app to statically link the functionality that you use from the standard library into your application.
 
-    As before in the `std` example, you can control the object file name and the named module interface file name with the following switches:
-    - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo "somethingelse.obj"`. By default, the compiler uses the same name as the module source file (`.ixx`) you are compiling. In the example, the output names are `std.obj` and `std.compat.obj` by default because we're compiling the module files `std.ixx` and `std.compat.obj`.
-    - [`/ifcOutput`](../build/reference/ifc-output.md) sets the name of the named module interface file (`.ifc`). For example, `/ifcOutput "somethingelse.ifc"`. By default, the compiler uses the same name as the module source file (`.ixx`) you are compiling. In the example, the generated `ifc` files are `std.ifc` and `std.compat.ifc` by default because we're compiling the module files `std.ixx` and `std.compat.ixx`.
+    You can control the object file name and the named module interface file name with the following switches:
+    - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo "somethingelse.obj"`. By default, the compiler uses the same name for the object file as the module source file (`.ixx`) you're compiling. In the example, the output names are `std.obj` and `std.compat.obj` by default because we're compiling the module files `std.ixx` and `std.compat.obj`.
+    - [`/ifcOutput`](../build/reference/ifc-output.md) sets the name of the named module interface file (`.ifc`). For example, `/ifcOutput "somethingelse.ifc"`. By default, the compiler uses the same name for the module interface file (`.ifc`) as the module source file (`.ixx`) you're compiling. In the example, the generated `ifc` files are `std.ifc` and `std.compat.ifc` by default because we're compiling the module files `std.ixx` and `std.compat.ixx`.
 
 1. To try out importing the `std.compat` library, create a file named `stdCompatExample.cpp` with the following content:
 
@@ -192,15 +192,16 @@ Before you can use `import std.compat;` you must compile the module interface fi
 
     We didn't have to specify `std.compat.ifc` on the command line because the compiler automatically looks for the `.ifc` file that matches the module name in an `import` statement. When the compiler encounters `import std.compat;` it finds `std.compat.ifc` since we put it in the same directory as the source code--relieving us of the need to specify it on the command line. If the `.ifc` file is in a different directory than the source code, or has a different name, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it.
 
-    When you import `std.compat`, you must also link against `std.obj` because `std.compat` builds on top of the implementation in `std.obj`.
+    When you import `std.compat`, you must also link against `std.obj` because `std.compat` builds on the implementation in `std.obj`.
 
     If you're building a single project, you can combine the steps of building the `std` and `std.compat` standard library named modules with the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` and `"%VCToolsInstallDir%\modules\std.compat.ixx"` (in that order) to the command line. This tutorial shows building the standard library modules as a separate step because you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects. But if it's convenient to build them all at once, you can, just make sure to put them before any `.cpp` files that consume them, and specify `/Fe` to name the built `exe` as shown in this example:
 
     ```cmd
-    cl /FestdCompatExample /std:c++latest /EHsc /nologo /W4 "%VCToolsInstallDir%\modules\std.ixx" "%VCToolsInstallDir%\modules\std.compat.ixx" stdCompatExample.cpp
+    cl /c /FestdCompatExample /std:c++latest /EHsc /nologo /W4 "%VCToolsInstallDir%\modules\std.ixx" "%VCToolsInstallDir%\modules\std.compat.ixx" stdCompatExample.cpp
+    link stdCompatExample.obj std.obj std.compat.obj
     ```
 
-    In this example, compiling your source code and linking the module's implementation into your application are separate steps. They don't have to be. You could have used `cl /std:c++latest /EHsc /nologo /W4 stdCompatExample.cpp std.obj std.compat.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects, in your build's link step.
+    In this example, compiling your source code and linking the module's implementation into your application are separate steps. They don't have to be. You could use `cl /std:c++latest /EHsc /nologo /W4 stdCompatExample.cpp std.obj std.compat.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects, in your build's link step.
 
     The previous compiler command produces an executable named `stdCompatExample.exe`. When you run it, it produces the following output:
 
