start draft (#3248)

* start draft

*  links

*  link

* acrolinx and  link

* tech review

*  comment

*  link broken by heading change

* tech review

* shortened up the trailing slashes

Co-authored-by: TylerMSFT <[email protected]>

Author: TylerMSFT

docs/build/reference/std-specify-language-standard-version.md

@@ -1,7 +1,7 @@
 ---
 title: "/std (Specify Language Standard Version)"
 description: "The MSVC compiler option /std specifies the C or C++ language standard supported by the compiler."
-ms.date: 09/11/2020
+ms.date: 10/29/2020
 f1_keywords: ["/std", "-std", "/std:c++14", "/std:c++17", "/std:c11", "/std:c17", "VC.Project.VCCLCompilerTool.CppLanguageStandard"]
 ms.assetid: 0acb74ba-1aa8-4c05-b96c-682988dc19bd
 ---
@@ -64,7 +64,7 @@ Starting in Visual Studio 2019 version 16.8, you may specify **`/std:c11`** or *
 
 When you specify **`/std:c11`** or **`/std:c17`**, MSVC supports all the required features of C11 and C17. The compiler options enable support for these functionalities:
 
-- **`_Pragma`**
+- [`_Pragma`](../../preprocessor/pragma-directives-and-the-pragma-keyword.md#the-_pragma-preprocessing-operator-c99-c11)
 
 - **`restrict`**
 

docs/preprocessor/pragma-directives-and-the-pragma-keyword.md

@@ -1,6 +1,7 @@
 ---
 title: "Pragma directives and the __pragma keyword"
-ms.date: "08/29/2019"
+description: "Describes the pragma directives available in Microsoft Visual C and C++ (MSVC)"
+ms.date: "10/30/2020"
 f1_keywords: ["#pragma"]
 helpviewer_keywords: ["#pragma directives, C/C++", "__pragma keyword", "pragma directives, C/C++", "pragmas, C/C++", "preprocessor", "pragmas", "preprocessor, pragmas", "pragma directives (#pragma)"]
 ms.assetid: 9867b438-ac64-4e10-973f-c3955209873f
@@ -11,16 +12,19 @@ Pragma directives specify machine- or operating system-specific compiler feature
 
 ## Syntax
 
-> **#pragma** *token-string*\
-> **__pragma(** *token-string* **)**
+> **#`pragma`** *token-string*\
+> **`__pragma(`** *token-string* **`)`** // two leading underscores - Microsoft specific extension
+> **`_Pragma(`** *string-literal* **`)`** // C99
 
 ## Remarks
 
 Each implementation of C and C++ supports some features unique to its host machine or operating system. Some programs, for example, must exercise precise control over the location of data in memory, or control the way certain functions receive parameters. The **#pragma** directives offer a way for each compiler to offer machine- and operating system-specific features, while maintaining overall compatibility with the C and C++ languages.
 
 Pragmas are machine- or operating system-specific by definition, and are typically different for every compiler. Pragmas can be used in conditional directives, to provide new preprocessor functionality, or to provide implementation-defined information to the compiler.
 
-The *token-string* is a series of characters that gives a specific compiler instruction and arguments, if any. The number sign (**#**) must be the first non-white-space character on the line that contains the pragma. White-space characters can separate the number sign and the word "pragma". Following **#pragma**, write any text that the translator can parse as preprocessing tokens. The argument to **#pragma** is subject to macro expansion.
+The *token-string* is a series of characters representing a specific compiler instruction and arguments, if any. The number sign (**#**) must be the first non-white-space character on the line that contains the pragma. White-space characters can separate the number sign and the word "pragma". Following **#pragma**, write any text that the translator can parse as preprocessing tokens. The argument to **#pragma** is subject to macro expansion.
+
+The *string-literal* is the input to `_Pragma`. Outer quotes and leading/trailing whitespace are removed. `\"` is replaced with `"` and `\\` is replaced with `\`.
 
 The compiler issues a warning when it finds a pragma that it doesn't recognize, and continues compilation.
 
@@ -99,9 +103,9 @@ cl /Zp8 some_file.cpp
 
 ## The __pragma() keyword
 
-The compiler also supports the Microsoft-specific **__pragma** keyword, which has the same functionality as the **#pragma** directive. The difference is, the **__pragma** keyword is usable inline in a macro definition. The **#pragma** directive isn't usable in a macro definition, because the compiler interprets the number sign character ('#') in the directive as the [stringizing operator (#)](../preprocessor/stringizing-operator-hash.md).
+The compiler also supports the Microsoft-specific **`__pragma`** keyword, which has the same functionality as the **`#pragma`** directive. The difference is, the **`__pragma`** keyword is usable inline in a macro definition. The **`#pragma`** directive isn't usable in a macro definition, because the compiler interprets the number sign character ('#') in the directive as the [stringizing operator (#)](../preprocessor/stringizing-operator-hash.md).
 
-The following code example demonstrates how the **__pragma** keyword can be used in a macro. This code is excerpted from the mfcdual.h header in the ACDUAL sample in "Compiler COM Support Samples":
+The following code example demonstrates how the **`__pragma`** keyword can be used in a macro. This code is excerpted from the *mfcdual.h* header in the ACDUAL sample in "Compiler COM Support Samples":
 
 ```cpp
 #define CATCH_ALL_DUAL \
@@ -121,6 +125,48 @@ END_CATCH_ALL \
 return _hr; \
 ```
 
+## The `_Pragma` preprocessing operator (C99, C++11)
+
+`_Pragma` is similar to the Microsoft-specific [`__pragma`](#the-__pragma-keyword) keyword, except it's part of the standard. It was introduced for C in C99. For C++, it was introduced in C++11.
+
+ It allows you to put pragmas into a macro definition. It has one leading underscore `_` instead of two leading underscores `__` that the Microsoft-specific keyword has, and the first letter is capitalized.
+
+The string literal should be what you would otherwise put following a *`#pragma`* statement. For example:
+
+```c
+#pragma message("--the #pragma way")
+_Pragma ("message( \"the _Pragma way\")") 
+```
+
+Quotation marks and back-slashes should be escaped, as shown above. A pragma string that isn't recognized is ignored.
+
+The following code example demonstrates how the **`_Pragma`** keyword could be used in an assert-like macro when you don't want to get a warning when the condition expression happens to be constant. 
+
+The macro definition uses the do/while(0) idiom for multi-statement macros so that it can be used as though it were one statement. See [C multi-line macro](https://stackoverflow.com/questions/1067226/c-multi-line-macro-do-while0-vs-scope-block) on Stack Overflow for more info. The _Pragma statement only applies to the line of code that follows it.
+
+```C
+// Compile with /W4
+
+#include <stdio.h>
+#include <stdlib.h>
+
+#define MY_ASSERT(BOOL_EXPRESSION) \
+    do { \
+        _Pragma("warning(suppress: 4127)") /* C4127 conditional expression is constant */  \
+        if (!(BOOL_EXPRESSION)) {   \
+            printf("MY_ASSERT FAILED: \"" #BOOL_EXPRESSION "\" on %s(%d)", __FILE__, __LINE__); \
+            exit(-1); \
+        } \
+    } while (0)
+
+int main()
+{
+    MY_ASSERT(0 && "Note that there is no warning: C4127 conditional expression is constant");
+
+    return 0;
+}
+```
+
 ## See also
 
 [C/C++ preprocessor reference](../preprocessor/c-cpp-preprocessor-reference.md)\