9/23/2021 AM Publish (#3794)

* draft fix

* fix for github #3346

* Document MASM instruction format including prefixes and option avxencoding (#3199)

* Document instruction format including prefixes and option avxencoding

* Add description to microsoft-macro-assembler-reference

* Revise to improve Acrolinx scores

* Further refinement for Acrolinx

* Still more changes to improve Acrolinx scores

* A few minor tweaks

* Update TOC for new content

* tweak formatting

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

* add links to ID2D1DCRenderTarget

* change to relative links

* remove global state reference

* tighten up struct tm

* fix formatting

* new local_info_struct & sys_info_struct plus updates (#3762)

* new local_info_struct & sys_info_struct plus updates

* acrolinx

* finish draft of local_info and sys_info, and update time_zone with an example of how to get one

* fix typos

* stash work so far on zoned_time class

* draft stub

* fix merge conflicts

* tech review

* add choose-enum, more zoned_time class work

* draft zoned_time

* read through fixes

* acrolinx

* cleanup

* a little word smithing

* tech review

* acrolinx and last of tech review

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

* Update issue templates

Added C++23 new issue template

* Fix Intel CET doc link per 3360

Co-authored-by: Colin Robertson <[email protected]>
Co-authored-by: TylerMSFT <[email protected]>
Co-authored-by: PRMerger15 <[email protected]>
Co-authored-by: jpmorgan-atMS <[email protected]>
Co-authored-by: opbld17 <[email protected]>
Co-authored-by: Dennis Rea <[email protected]>
Co-authored-by: PRMerger17 <[email protected]>
Co-authored-by: Tyler Whitney <[email protected]>

Author: 9 people

.github/ISSUE_TEMPLATE/new-c---2020-stl-library-documentation-topic-.md

@@ -2,10 +2,9 @@
 name: 'New C++ 2020 STL library documentation topic '
 about: Create a C++ 2020 doc tracking work item
 title: ''
-labels: STL doc work, C++20
+labels: C++20, STL doc work
 assignees: ''
-milestone: backlog
-project: C++20
+
 ---
 
 ISO paper for this feature: [PaperID]()

.github/ISSUE_TEMPLATE/new-c---2023-stl-library-documentation-topic.md

@@ -0,0 +1,11 @@
+---
+name: New C++ 2023 STL library documentation topic
+about: Create an issue to track C++ 2023 STL doc work
+title: ''
+labels: C++23
+assignees: ''
+
+---
+
+ISO paper for this feature: [PaperID](http link to iso paper)
+First implemented in: VS 20YY major.minor

docs/build/reference/cetcompat.md

@@ -1,7 +1,7 @@
 ---
 description: "Learn more about: /CETCOMPAT (CET Shadow Stack compatible)"
 title: "/CETCOMPAT (CET Shadow Stack compatible)"
-ms.date: "09/01/2020"
+ms.date: 09/22/2021
 f1_keywords: ["/CETCOMPAT"]
 helpviewer_keywords: ["/CETCOMPAT linker option", "/CETCOMPAT"]
 ---
@@ -21,7 +21,7 @@ Specifies that the executable shouldn't be marked compatible with CET Shadow Sta
 
 ## Remarks
 
-Control-flow Enforcement Technology (CET) Shadow Stack is a computer processor feature that provides capabilities to defend against return-oriented programming (ROP) based malware attacks. For more information, see [Intel Control-flow Enforcement Technology Preview](https://software.intel.com/sites/default/files/managed/4d/2a/control-flow-enforcement-technology-preview.pdf).
+Control-flow Enforcement Technology (CET) Shadow Stack is a computer processor feature. It provides capabilities to defend against return-oriented programming (ROP) based malware attacks. For more information, see [A Technical Look at Intel’s Control-flow Enforcement Technology](https://software.intel.com/content/www/us/en/develop/articles/technical-look-control-flow-enforcement-technology.html).
 
 The **`/CETCOMPAT`** linker option tells the linker to mark the binary as CET Shadow Stack-compatible. **`/CETCOMPAT:NO`** marks the binary as not compatible with CET Shadow Stack. If both options are specified on the command line, the last one specified is used. This switch is currently only applicable to x86 and x64 architectures.
 
@@ -37,7 +37,7 @@ Starting in Visual Studio 2019 version 16.7:
 
 1. Select the **CET Shadow Stack Compatible** property.
 
-1. In the dropdown control, choose **`Yes (/CETCOMPAT)`** to mark the binary as CET Shadow Stack compatible , or **`No (/CETCOMPAT:NO)`** to mark it as non-compatible.
+1. In the dropdown control, choose **`Yes (/CETCOMPAT)`** to mark the binary as CET Shadow Stack compatible, or **`No (/CETCOMPAT:NO)`** to mark it as non-compatible.
 
 In previous versions of Visual Studio 2019:
 

docs/c-runtime-library/reference/mkgmtime-mkgmtime32-mkgmtime64.md

@@ -1,18 +1,17 @@
 ---
 title: "_mkgmtime, _mkgmtime32, _mkgmtime64"
 description: "Describes the _mkgmtime, _mkgmtime32, and _mkgmtime64 C Runtime library functions, and gives examples of how to use them."
-ms.date: "4/2/2020"
+ms.date: 09/22/2021
 api_name: ["_mkgmtime32", "_mkgmtime64", "_mkgmtime", "_o__mkgmtime32", "_o__mkgmtime64"]
 api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"]
 api_type: ["DLLExport"]
 topic_type: ["apiref"]
 f1_keywords: ["_mkgmtime64", "mkgmtime32", "_mkgmtime32", "mkgmtime", "mkgmtime64", "_mkgmtime"]
 helpviewer_keywords: ["mkgmtime32 function", "time functions", "mkgmtime function", "_mkgmtime function", "converting times", "mkgmtime64 function", "_mkgmtime64 function", "_mkgmtime32 function", "time, converting"]
-ms.assetid: b4ca2b67-e198-4f43-b3e2-e8ad6bd01867
 ---
-# _mkgmtime, _mkgmtime32, _mkgmtime64
+# `_mkgmtime`, `_mkgmtime32`, `_mkgmtime64`
 
-Converts a UTC time represented by a **`struct`** **tm** to a UTC time represented by a **time_t** type.
+Converts a UTC time represented by a **`struct tm`** to a UTC time represented by a **`time_t`** type.
 
 ## Syntax
 
@@ -30,26 +29,24 @@ __time64_t _mkgmtime64(
 
 ### Parameters
 
-*timeptr*\
-A pointer to the UTC time as a **`struct`** **tm** to convert.
+*`timeptr`*\
+A pointer to the UTC time as a **`struct tm`** to convert.
 
 ## Return Value
 
-A quantity of type **__time32_t** or **__time64_t** representing the number of seconds elapsed since midnight, January 1, 1970, in Coordinated Universal Time (UTC). If the date is out of range (see the Remarks section) or the input can't be interpreted as a valid time, the return value is -1.
+A quantity of type **`__time32_t`** or **`__time64_t`** representing the number of seconds elapsed since midnight, January 1, 1970, in Coordinated Universal Time (UTC). If the date is out of range (see the Remarks section) or the input can't be interpreted as a valid time, the return value is -1.
 
 ## Remarks
 
-The **_mkgmtime32** and **_mkgmtime64** functions convert a UTC time to a **__time32_t** or **__time64_t** type representing the time in UTC. To convert a local time to UTC time, use **mktime**, **_mktime32**, and **_mktime64** instead.
+The **`_mkgmtime32`** and **`_mkgmtime64`** functions convert a UTC time to a **`__time32_t`** or **`__time64_t`** type representing the time in UTC. To convert a local time to UTC time, use **`mktime`**, **`_mktime32`**, and **`_mktime64`** instead.
 
-**_mkgmtime** is an inline function that evaluates to **_mkgmtime64**, and **time_t** is equivalent to **__time64_t**. If you need to force the compiler to interpret **time_t** as the old 32-bit **time_t**, you can define **_USE_32BIT_TIME_T**. We don't recommend it, because your application might fail after January 18, 2038, the maximum range of a 32-bit **time_t**. It's not allowed at all on 64-bit platforms.
+**_mkgmtime** is an inline function that evaluates to **`_mkgmtime64`**, and **`time_t`** is equivalent to **`__time64_t`**. If you need to force the compiler to interpret **`time_t`** as the old 32-bit **`time_t`**, you can define **`_USE_32BIT_TIME_T`**. We don't recommend it, because your application might fail after January 18, 2038, the maximum range of a 32-bit **`time_t`**. It's not allowed at all on 64-bit platforms.
 
-The time structure passed in is changed as follows, in the same way as it's changed by the **_mktime** functions: the **tm_wday** and **tm_yday** fields are set to new values based on the values of **tm_mday** and **tm_year**. Because the time is assumed to be UTC, the **tm_isdst** field is ignored.
+The time structure passed in is changed as follows, in the same way as it's changed by the **`_mktime`** functions: the **`tm_wday`** and **`tm_yday`** fields are set to new values based on the values of **`tm_mday`** and **`tm_year`**. Because the time is assumed to be UTC, the **`tm_isdst`** field is ignored.
 
-The range of the **_mkgmtime32** function is from midnight, January 1, 1970, UTC to 23:59:59 January 18, 2038, UTC. The range of **_mkgmtime64** is from midnight, January 1, 1970, UTC to 23:59:59, December 31, 3000, UTC. An out-of-range date results in a return value of -1. The range of **_mkgmtime** depends on whether **_USE_32BIT_TIME_T** is defined. When it's not defined, which is the default, the range is the same as **_mkgmtime64**. Otherwise, the range is limited to the 32-bit range of **_mkgmtime32**.
+The range of the **`_mkgmtime32`** function is from midnight, January 1, 1970, UTC to 23:59:59 January 18, 2038, UTC. The range of **`_mkgmtime64`** is from midnight, January 1, 1970, UTC to 23:59:59, December 31, 3000, UTC. An out-of-range date results in a return value of -1. The range of **`_mkgmtime`** depends on whether **`_USE_32BIT_TIME_T`** is defined. When it's not defined, which is the default, the range is the same as **`_mkgmtime64`**. Otherwise, the range is limited to the 32-bit range of **`_mkgmtime32`**.
 
-Both **gmtime** and **localtime** use a common static buffer for the conversion. If you supply this buffer to **_mkgmtime**, the previous contents are destroyed.
-
-By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md).
+Both **`gmtime`** and **`localtime`** use a common static buffer for the conversion. If you supply this buffer to **`_mkgmtime`**, the previous contents are destroyed.
 
 ## Examples
 
@@ -98,7 +95,7 @@ Local Time: Thu Feb 15 17:14:52 2007
 Greenwich Mean Time: Fri Feb 16 01:14:52 2007
 ```
 
-The following example shows how the incomplete structure is filled out by **_mkgmtime**. It computes values for both the day of the week and of the year.
+The following example shows how the incomplete structure is filled out by **`_mkgmtime`**. It computes values for both the day of the week and of the year.
 
 ```C
 // crt_mkgmtime2.c
@@ -145,10 +142,10 @@ t.tm_yday = 42
 ## See also
 
 [Time Management](../../c-runtime-library/time-management.md)\
-[asctime, _wasctime](asctime-wasctime.md)\
-[asctime_s, _wasctime_s](asctime-s-wasctime-s.md)\
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)\
-[gmtime_s, _gmtime32_s, _gmtime64_s](gmtime-s-gmtime32-s-gmtime64-s.md)\
-[localtime_s, _localtime32_s, _localtime64_s](localtime-s-localtime32-s-localtime64-s.md)\
-[mktime, _mktime32, _mktime64](mktime-mktime32-mktime64.md)\
-[time, _time32, _time64](time-time32-time64.md)
+[`asctime`, `_wasctime`](asctime-wasctime.md)\
+[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md)\
+[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\
+[`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](gmtime-s-gmtime32-s-gmtime64-s.md)\
+[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)\
+[`mktime`, `_mktime32`, `_mktime64`](mktime-mktime32-mktime64.md)\
+[`time`, `_time32`, `_time64`](time-time32-time64.md)

docs/mfc/reference/cdcrendertarget-class.md

@@ -1,18 +1,17 @@
 ---
 description: "Learn more about: CDCRenderTarget Class"
 title: "CDCRenderTarget Class"
-ms.date: "11/04/2016"
+ms.date: 09/22/2021
 f1_keywords: ["CDCRenderTarget", "AFXRENDERTARGET/CDCRenderTarget", "AFXRENDERTARGET/CDCRenderTarget::CDCRenderTarget", "AFXRENDERTARGET/CDCRenderTarget::Attach", "AFXRENDERTARGET/CDCRenderTarget::BindDC", "AFXRENDERTARGET/CDCRenderTarget::Create", "AFXRENDERTARGET/CDCRenderTarget::Detach", "AFXRENDERTARGET/CDCRenderTarget::GetDCRenderTarget", "AFXRENDERTARGET/CDCRenderTarget::m_pDCRenderTarget"]
 helpviewer_keywords: ["CDCRenderTarget [MFC], CDCRenderTarget", "CDCRenderTarget [MFC], Attach", "CDCRenderTarget [MFC], BindDC", "CDCRenderTarget [MFC], Create", "CDCRenderTarget [MFC], Detach", "CDCRenderTarget [MFC], GetDCRenderTarget", "CDCRenderTarget [MFC], m_pDCRenderTarget"]
-ms.assetid: aa8059c9-08e6-49e4-9b8c-00fa54077a61
 ---
-# CDCRenderTarget Class
+# `CDCRenderTarget` class
 
-A wrapper for ID2D1DCRenderTarget.
+A wrapper for [`ID2D1DCRenderTarget`](/windows/win32/api/d2d1/nn-d2d1-id2d1dcrendertarget).
 
 ## Syntax
 
-```
+```cpp
 class CDCRenderTarget : public CRenderTarget;
 ```
 
@@ -22,43 +21,41 @@ class CDCRenderTarget : public CRenderTarget;
 
 |Name|Description|
 |----------|-----------------|
-|[CDCRenderTarget::CDCRenderTarget](#cdcrendertarget)|Constructs a CDCRenderTarget object.|
+|[`CDCRenderTarget::CDCRenderTarget`](#cdcrendertarget)|Constructs a `CDCRenderTarget` object.|
 
 ### Public Methods
 
 |Name|Description|
 |----------|-----------------|
-|[CDCRenderTarget::Attach](#attach)|Attaches existing render target interface to the object|
-|[CDCRenderTarget::BindDC](#binddc)|Binds the render target to the device context to which it issues drawing commands|
-|[CDCRenderTarget::Create](#create)|Creates a CDCRenderTarget.|
-|[CDCRenderTarget::Detach](#detach)|Detaches render target interface from the object|
-|[CDCRenderTarget::GetDCRenderTarget](#getdcrendertarget)|Returns ID2D1DCRenderTarget interface|
+|[`CDCRenderTarget::Attach`](#attach)|Attaches existing render target interface to the object|
+|[`CDCRenderTarget::BindDC`](#binddc)|Binds the render target to the device context to which it issues drawing commands|
+|[`CDCRenderTarget::Create`](#create)|Creates a `CDCRenderTarget`.|
+|[`CDCRenderTarget::Detach`](#detach)|Detaches render target interface from the object|
+|[`CDCRenderTarget::GetDCRenderTarget`](#getdcrendertarget)|Returns an [`ID2D1DCRenderTarget`](/windows/win32/api/d2d1/nn-d2d1-id2d1dcrendertarget) interface|
 
 ### Public Operators
 
 |Name|Description|
 |----------|-----------------|
-|[CDCRenderTarget::operator ID2D1DCRenderTarget*](#operator_id2d1dcrendertarget_star)|Returns ID2D1DCRenderTarget interface|
+|[`CDCRenderTarget::operator ID2D1DCRenderTarget*`](#operator_id2d1dcrendertarget_star)|Returns an [`ID2D1DCRenderTarget`](/windows/win32/api/d2d1/nn-d2d1-id2d1dcrendertarget) interface|
 
 ### Protected Data Members
 
 |Name|Description|
 |----------|-----------------|
-|[CDCRenderTarget::m_pDCRenderTarget](#m_pdcrendertarget)|A pointer to an ID2D1DCRenderTarget object.|
+|[CDCRenderTarget::m_pDCRenderTarget](#m_pdcrendertarget)|A pointer to an [`ID2D1DCRenderTarget`](/windows/win32/api/d2d1/nn-d2d1-id2d1dcrendertarget) object.|
 
 ## Inheritance Hierarchy
 
-[CObject](../../mfc/reference/cobject-class.md)
-
-[CRenderTarget](../../mfc/reference/crendertarget-class.md)
-
-[CDCRenderTarget](../../mfc/reference/cdcrendertarget-class.md)
+[`CObject`](../../mfc/reference/cobject-class.md)\
+[`CRenderTarget`](../../mfc/reference/crendertarget-class.md)\
+[`CDCRenderTarget`](../../mfc/reference/cdcrendertarget-class.md)
 
 ## Requirements
 
-**Header:** afxrendertarget.h
+**Header:** `afxrendertarget.h`
 
-## <a name="attach"></a> CDCRenderTarget::Attach
+## <a name="attach"></a> `CDCRenderTarget::Attach`
 
 Attaches existing render target interface to the object
 
@@ -68,99 +65,99 @@ void Attach(ID2D1DCRenderTarget* pTarget);
 
 ### Parameters
 
-*pTarget*<br/>
-Existing render target interface. Cannot be NULL
+*`pTarget`*\
+Existing render target interface. Can't be `NULL`
 
-## <a name="binddc"></a> CDCRenderTarget::BindDC
+## <a name="binddc"></a> `CDCRenderTarget::BindDC`
 
 Binds the render target to the device context to which it issues drawing commands
 
-```
+```cpp
 BOOL BindDC(
     const CDC& dc,
     const CRect& rect);
 ```
 
 ### Parameters
 
-*dc*<br/>
+*`dc`*\
 The device context to which the render target issues drawing commands
 
-*rect*<br/>
-The dimensions of the handle to a device context (HDC) to which the render target is bound
+*`rect`*\
+The dimensions of the handle to a device context (`HDC`) to which the render target is bound
 
 ### Return Value
 
-If the method succeeds, it returns TRUE. Otherwise, it returns FALSE.
+If the method succeeds, it returns `TRUE`. Otherwise, it returns `FALSE`.
 
-## <a name="cdcrendertarget"></a> CDCRenderTarget::CDCRenderTarget
+## <a name="cdcrendertarget"></a> `CDCRenderTarget::CDCRenderTarget`
 
-Constructs a CDCRenderTarget object.
+Constructs a `CDCRenderTarget` object.
 
-```
+```cpp
 CDCRenderTarget();
 ```
 
-## <a name="create"></a> CDCRenderTarget::Create
+## <a name="create"></a> `CDCRenderTarget::Create`
 
-Creates a CDCRenderTarget.
+Creates a `CDCRenderTarget`.
 
-```
+```cpp
 BOOL Create(const D2D1_RENDER_TARGET_PROPERTIES& props);
 ```
 
 ### Parameters
 
-*props*<br/>
+*`props`*\
 The rendering mode, pixel format, remoting options, DPI information, and the minimum DirectX support required for hardware rendering.
 
 ### Return Value
 
-If the method succeeds, it returns TRUE. Otherwise, it returns FALSE.
+If the method succeeds, it returns `TRUE`. Otherwise, it returns `FALSE`.
 
-## <a name="detach"></a> CDCRenderTarget::Detach
+## <a name="detach"></a> `CDCRenderTarget::Detach`
 
 Detaches render target interface from the object
 
-```
+```cpp
 ID2D1DCRenderTarget* Detach();
 ```
 
 ### Return Value
 
 Pointer to detached render target interface.
 
-## <a name="getdcrendertarget"></a> CDCRenderTarget::GetDCRenderTarget
+## <a name="getdcrendertarget"></a> `CDCRenderTarget::GetDCRenderTarget`
 
-Returns ID2D1DCRenderTarget interface
+Returns an [`ID2D1DCRenderTarget`](/windows/win32/api/d2d1/nn-d2d1-id2d1dcrendertarget)
 
-```
+```cpp
 ID2D1DCRenderTarget* GetDCRenderTarget();
 ```
 
 ### Return Value
 
-Pointer to an ID2D1DCRenderTarget interface or NULL if object is not initialized yet.
+Pointer to an [`ID2D1DCRenderTarget`](/windows/win32/api/d2d1/nn-d2d1-id2d1dcrendertarget) interface or `NULL` if object isn't initialized yet.
 
-## <a name="m_pdcrendertarget"></a> CDCRenderTarget::m_pDCRenderTarget
+## <a name="m_pdcrendertarget"></a> `CDCRenderTarget::m_pDCRenderTarget`
 
-A pointer to an ID2D1DCRenderTarget object.
+A pointer to an [`ID2D1DCRenderTarget`](/windows/win32/api/d2d1/nn-d2d1-id2d1dcrendertarget) object.
 
-```
+```cpp
 ID2D1DCRenderTarget* m_pDCRenderTarget;
 ```
 
-## <a name="operator_id2d1dcrendertarget_star"></a> CDCRenderTarget::operator ID2D1DCRenderTarget*
+## <a name="operator_id2d1dcrendertarget_star"></a> `CDCRenderTarget::operator ID2D1DCRenderTarget*`
 
-Returns ID2D1DCRenderTarget interface
+Returns an [`ID2D1DCRenderTarget`](/windows/win32/api/d2d1/nn-d2d1-id2d1dcrendertarget) interface
 
-```
+```cpp
 operator ID2D1DCRenderTarget*();
 ```
 
 ### Return Value
 
-Pointer to an ID2D1DCRenderTarget interface or NULL if object is not initialized yet.
+Pointer to an `[`ID2D1DCRenderTarget`](/windows/win32/api/d2d1/nn-d2d1-id2d1dcrendertarget) interface or NULL if object isn't initialized yet.
 
 ## See also
 

docs/standard-library/bit-enum.md

@@ -5,7 +5,8 @@ ms.date: "08/27/2020"
 f1_keywords: ["bit/std::endian"]
 helpviewer_keywords: ["std::endian"]
 ---
-# endian enum
+
+# `endian` enum
 
 Indicates the endianness of all scalar types.
 
@@ -32,12 +33,12 @@ All native scalar types are little-endian for the platforms that Microsoft Visua
 
 ## Requirements
 
-**Header:** \<bit>
+**Header:** `<bit>`
 
-**Namespace:** std
+**Namespace:** `std`
 
-[`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required.
+Compiler option: [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required.
 
 ## See also
 
-[\<bit>](../standard-library/bit.md)  
+[`<bit>`](../standard-library/bit.md)