Acrolinx pass

Author: Colin Robertson

docs/preprocessor/alloc-text.md

@@ -8,21 +8,21 @@ no-loc: ["pragma"]
 ---
 # `alloc_text` pragma
 
-Names the code section where the specified function definitions are to reside. The pragma must occur between a function declarator and the function definition for the named functions.
+Names the code section where the specified function definitions are placed. The pragma must occur between a function declarator and the function definition for the named functions.
 
 ## Syntax
 
-> **`#pragma alloc_text(`** "*textsection*" **`,`** *function1* [**`,`** *function2* ... ] **`)`**
+> **`#pragma alloc_text(`** "*text-section*" **`,`** *function_1* [**`,`** *function_2* ... ] **`)`**
 
 ## Remarks
 
-The **`alloc_text`** pragma does not handle C++ member functions or overloaded functions. It is applicable only to functions declared with C linkage — that is, functions declared with the **`extern "C"`** linkage specification. If you attempt to use this pragma on a function with C++ linkage, a compiler error is generated.
+The **`alloc_text`** pragma doesn't handle C++ member functions or overloaded functions. It's applicable only to functions declared with C linkage, that is, functions declared with the **`extern "C"`** linkage specification. If you attempt to use this pragma on a function with C++ linkage, a compiler error is generated.
 
-Since function addressing using **`__based`** is not supported, specifying section locations requires the use of the **`alloc_text`** pragma. The name specified by *textsection* should be enclosed in double quotation marks.
+Since function addressing using **`__based`** isn't supported, specifying section locations requires the use of the **`alloc_text`** pragma. The name specified by *text-section* should be enclosed in double quotation marks.
 
 The **`alloc_text`** pragma must appear after the declarations of any of the specified functions and before the definitions of these functions.
 
-Functions referenced in an **`alloc_text`** pragma should be defined in the same module as the pragma. Otherwise, if an undefined function is later compiled into a different text section, the error may or may not be caught. Although the program will usually run correctly, the function will not be allocated in the intended sections.
+Functions referenced in an **`alloc_text`** pragma should be defined in the same module as the pragma. Otherwise, if an undefined function is later compiled into a different text section, the error may or may not be caught. Although the program will usually run correctly, the function won't be allocated in the intended sections.
 
 Other limitations on **`alloc_text`** are as follows:
 

docs/preprocessor/comment-c-cpp.md

@@ -16,17 +16,17 @@ Places a comment record into an object file or executable file.
 
 ## Remarks
 
-The *comment-type* is one of the predefined identifiers, described below, that specifies the type of comment record. The optional *comment-string* is a string literal that provides additional information for some comment types. Because *comment-string* is a string literal, it obeys all the rules for string literals with respect to escape characters, embedded quotation marks (`"`), and concatenation.
+The *comment-type* is one of the predefined identifiers, described below, that specifies the type of comment record. The optional *comment-string* is a string literal that provides additional information for some comment types. Because *comment-string* is a string literal, it obeys all the rules for string literals on use of escape characters, embedded quotation marks (`"`), and concatenation.
 
 ### compiler
 
 Places the name and version number of the compiler in the object file. This comment record is ignored by the linker. If you supply a *comment-string* parameter for this record type, the compiler generates a warning.
 
 ### lib
 
-Places a library-search record in the object file. This comment type must be accompanied by a *comment-string* parameter containing the name (and possibly the path) of the library that you want the linker to search. The library name follows the default library-search records in the object file; the linker searches for this library just as if you had named it on the command line provided that the library is not specified with [`/nodefaultlib`](../build/reference/nodefaultlib-ignore-libraries.md). You can place multiple library-search records in the same source file; each record appears in the object file in the same order in which it is encountered in the source file.
+Places a library-search record in the object file. This comment type must be accompanied by a *comment-string* parameter that has the name (and possibly the path) of the library that you want the linker to search. The library name follows the default library-search records in the object file. The linker searches for this library the same way as if you specified it on the command line, as long as the library isn't specified by using [`/nodefaultlib`](../build/reference/nodefaultlib-ignore-libraries.md). You can place multiple library-search records in the same source file. Each record appears in the object file in the same order it's found in the source file.
 
-If the order of the default library and an added library is important, compiling with the [`/Zl`](../build/reference/zl-omit-default-library-name.md) switch will prevent the default library name from being placed in the object module. A second comment pragma then can be used to insert the name of the default library after the added library. The libraries listed with these pragma directives will appear in the object module in the same order they are found in the source code.
+If the order of the default library and an added library is important, compiling with the [`/Zl`](../build/reference/zl-omit-default-library-name.md) switch will prevent the default library name from being placed in the object module. A second comment pragma then can be used to insert the name of the default library after the added library. The libraries listed with these pragma directives will appear in the object module in the same order they're found in the source code.
 
 ### linker
 
@@ -56,7 +56,7 @@ Places a general comment in the object file. The *comment-string* parameter cont
 
 ## Examples
 
-The following pragma causes the linker to search for the EMAPI.LIB library while linking. The linker searches first in the current working directory and then in the path specified in the LIB environment variable.
+The following pragma causes the linker to search for the EMAPI.LIB library while linking. The linker searches first in the current working directory, and then in the path specified in the LIB environment variable.
 
 ```C
 #pragma comment( lib, "emapi" )
@@ -68,7 +68,7 @@ The following pragma causes the compiler to place the name and version number of
 #pragma comment( compiler )
 ```
 
-For comments that take a *comment-string* parameter, you can use a macro in any place where you would use a string literal, provided that the macro expands to a string literal. You can also concatenate any combination of string literals and macros that expand to string literals. For example, the following statement is acceptable:
+For comments that take a *comment-string* parameter, you can use a macro in any place where you would use a string literal, as long as the macro expands to a string literal. You can also concatenate any combination of string literals and macros that expand to string literals. For example, the following statement is acceptable:
 
 ```C
 #pragma comment( user, "Compiled on " __DATE__ " at " __TIME__ )

docs/preprocessor/execution-character-set.md

@@ -8,7 +8,7 @@ no-loc: ["pragma"]
 ---
 # `execution_character_set` pragma
 
-Specifies the execution character set used for string and character literals. This directive is not needed for literals marked with the `u8` prefix.
+Specifies the execution character set used for string and character literals. This directive isn't needed for literals marked with the `u8` prefix.
 
 ## Syntax
 
@@ -25,9 +25,9 @@ This compiler directive is obsolete starting in Visual Studio 2015 Update 2. We
 
 The `#pragma execution_character_set("utf-8")` directive tells the compiler to encode narrow character and narrow string literals in your source code as UTF-8 in the executable. This output encoding is independent of the source file encoding used.
 
-By default, the compiler encodes narrow characters and narrow strings by using the current code page as the execution character set. This means that Unicode or DBCS characters in a literal that are outside the range of the current code page are converted to the default replacement character in the output. Unicode and DBCS characters are truncated to their low-order byte. This is almost certainly not what you intend. You can specify UTF-8 encoding for literals in the source file by using a `u8` prefix. The compiler passes these UTF-8 encoded strings to the output unchanged. Narrow character literals prefixed by using u8 must fit in one byte, or they are truncated on output.
+By default, the compiler encodes narrow characters and narrow strings by using the current code page as the execution character set. It means that Unicode or DBCS characters outside the range of the current code page get converted to the default replacement character in the output. Unicode and DBCS characters are truncated to their low-order byte, which is almost never what you intend. You can specify UTF-8 encoding for literals in the source file by using a `u8` prefix. The compiler passes these UTF-8 encoded strings to the output unchanged. Narrow character literals prefixed by using u8 must fit in a byte, or they're truncated on output.
 
-By default, Visual Studio uses the current code page as the source character set used to interpret your source code for output. When a file is read in, Visual Studio interprets it according to the current code page unless the file code page was set, or unless a byte-order mark (BOM) or UTF-16 characters are detected at the beginning of the file. Because UTF-8 can't be set as the current code page, when the automatic detection encounters source files encoded as UTF-8 without a BOM, Visual Studio assumes that they are encoded by using the current code page. Characters in the source file that are outside the range of the specified or automatically detected code page can cause compiler warnings and errors.
+By default, Visual Studio uses the current code page as the source character set used to interpret your source code for output. When a file is read in, Visual Studio interprets it according to the current code page unless the file code page was set, or unless a byte-order mark (BOM) or UTF-16 characters are detected at the beginning of the file. You can't set UTF-8 as the current code page in some versions of Windows. When the automatic detection finds source files encoded as UTF-8 without a BOM in those versions, Visual Studio assumes they're encoded by using the current code page. Characters in the source file that are outside the range of the specified or automatically detected code page can cause compiler warnings and errors.
 
 ## See also
 

docs/preprocessor/include-alias.md

@@ -79,7 +79,7 @@ The filename reported in error messages, or as the value of the predefined `__FI
 #include "VERYLONGFILENAME.H"
 ```
 
-An error in *VERYLONGFILENAME.H* produces the following error message:
+An error in *`VERYLONGFILENAME.H`* produces the following error message:
 
 ```Output
 myfile.h(15) : error C2059 : syntax error
@@ -93,7 +93,7 @@ Also note that transitivity isn't supported. Given the following directives,
 #include "one.h"
 ```
 
-the compiler searches for the file *two.h* rather than *three.h*.
+the compiler searches for the file *`two.h`* rather than *`three.h`*.
 
 ## See also