Revamp docs for VT v. APIs and long term roadmap

This change runs through almost every doc in our portfolio fixing up: - Formatting issues and warnings across the board - Provides disclaimers on all APIs we wish would be less used in favor of unifying on VT - Provides suggestions on alternative VT sequences to API usage - Gives an understanding of console APIs vs VT sequences and why we're moving to the latter, generally speaking - Gives an overview of the history and roadmap for the console platform
MicrosoftDocs · Oct 29, 2020 · a002f34 · a002f34
2 parents 8dc1ab9 + 12225b3
commit a002f34
Show file tree

Hide file tree

Showing 145 changed files with 2,730 additions and 6,859 deletions.
diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json
@@ -22,7 +22,7 @@
     }
   ],
   "notification_subscribers": [
-    "richturn@microsoft.com",
+    "cinnamon@microsoft.com",
     "duhowett@microsoft.com",
     "miniksa@microsoft.com"
   ],

diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 Welcome to the Windows Console documentation repo. The MSDN Console Docs are generated from the markdown stored in this repo.
 The published docs can be found at [https://docs.microsoft.com/windows/console/](https://docs.microsoft.com/windows/console/)
 
-For code issues related to the Windows Console, Windows Terminal, and related command-line and terminal tooling products acquired with Windows, from the Windows Store, or other sources like GitHub, please check out the [Microsoft/Terminal](https://github.com/microsoft/terminal) repository.
+For code issues related to the Windows Console, Windows Terminal, and related command-line and terminal tooling products acquired with Windows, from the Windows Store, or other sources like GitHub, please check out the [microsoft/terminal](https://github.com/microsoft/terminal) repository.
 
 # Metadata
 Each content page in this repo requires some metadata expressed as [YAML](https://en.wikipedia.org/wiki/YAML), stored at the top of each doc between '---' markers. For example:
@@ -35,7 +35,7 @@ While some metadata is stored per file (e.g. above), common metadata required by
     "fileMetadata": {
       "ms.prod": { "/console/**.yml": "windows"},
       "ms.technology": { "/console/**.yml": "desktop"},
-      "manager": {"/console/**.yml": "richturn"}
+      "manager": {"/console/**.yml": "miniksa"}
     }
   }
 }

diff --git a/docs/TOC.md b/docs/TOC.md
@@ -1,4 +1,9 @@
 # [Home](index.md) 
+
+## [Ecosystem Roadmap](ecosystem-roadmap.md)
+## [Definitions](definitions.md)
+## [Console APIs vs. Virtual Terminal](classic-vs-vt.md)
+
 # [About Character Mode Applications](about-character-mode-applications.md) 
 ## [Input And Output Methods](input-and-output-methods.md) 
 ## [Console Code Pages](console-code-pages.md)
@@ -56,7 +61,7 @@
 ### [GenerateConsoleCtrlEvent](generateconsolectrlevent.md) 
 ### [GetConsoleAlias](getconsolealias.md) 
 ### [GetConsoleAliases](getconsolealiases.md) 
-### [GetConsoleAliaseslength](getconsolealiaseslength.md) 
+### [GetConsoleAliasesLength](getconsolealiaseslength.md) 
 ### [GetConsoleAliasExes](getconsolealiasexes.md) 
 ### [GetConsoleAliasExesLength](getconsolealiasexeslength.md) 
 ### [GetConsoleCP](getconsolecp.md) 

diff --git a/docs/about-character-mode-applications.md b/docs/about-character-mode-applications.md
@@ -3,7 +3,7 @@ title: About Consoles
 description: Consoles provide high-level support for simple character mode applications that interact with the user by using functions that read from standard input and write to standard output or standard error.
 author: miniksa
 ms.author: miniksa
-ms.topic: article
+ms.topic: conceptual
 keywords: console, character mode applications, command line applications, terminal applications, console api
 MS-HAID:
 - '\_win32\_about\_character\_mode\_applications'
@@ -19,13 +19,13 @@ ms.assetid: 39204f0e-b0b8-4f92-af8e-e146ac06c454
 
 Character mode (or "command-line") applications:
 
-1. [Optionally] Read data from standard input (stdin)
+1. \[Optionally\] Read data from standard input (stdin)
 2. Do "work"
-3. [Optionally] Write data to standard output (stdout) or standard error (stderr)
+3. \[Optionally\] Write data to standard output (stdout) or standard error (stderr)
 
 Character mode applications communicate with the end-user through a "console" (or "terminal") application. A console converts user input from keyboard, mouse, touch-screen, pen, etc., and sends it to a character mode application's stdin. A console may also display a character mode application's text output on the user's screen.
 
-In Windows, the console is built-in and provides a rich API through which character mode applications can interact with the user.
+In Windows, the console is built-in and provides a rich API through which character mode applications can interact with the user. However, in the recent era, the console team is encouraging all character mode applications to be developed with [virtual terminal sequences](console-virtual-terminal-sequences.md) over the classic API calls for maximum compatibility between Windows and other operating systems. More details on this transition and the trade offs involved can be found in our discussion of [classic APIs versus virtual terminal sequences](classic-vs-vt.md).
 
 - [Consoles](consoles.md)
 - [Input and Output Methods](input-and-output-methods.md)
@@ -34,11 +34,3 @@ In Windows, the console is built-in and provides a rich API through which charac
 - [Console Aliases](console-aliases.md)
 - [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md)
 - [Console Application Issues](console-application-issues.md)
-
-
-
-
-
-
-
-
diff --git a/docs/addconsolealias.md b/docs/addconsolealias.md
@@ -36,11 +36,11 @@ api_type:
 
 # AddConsoleAlias function
 
+[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)]
 
 Defines a console alias for the specified executable.
 
-Syntax
-------
+## Syntax
 
 ```C
 BOOL WINAPI AddConsoleAlias(
@@ -50,8 +50,7 @@ BOOL WINAPI AddConsoleAlias(
 );
 ```
 
-Parameters
-----------
+## Parameters
 
 *Source* \[in\]  
 The console alias to be mapped to the text specified by *Target*.
@@ -62,69 +61,34 @@ The text to be substituted for *Source*. If this parameter is **NULL**, then the
 *ExeName* \[in\]  
 The name of the executable file for which the console alias is to be defined.
 
-Return value
-------------
+## Return value
 
 If the function succeeds, the return value is **TRUE**.
 
 If the function fails, the return value is **FALSE**. To get extended error information, call [**GetLastError**](https://msdn.microsoft.com/library/windows/desktop/ms679360).
 
-Remarks
--------
+## Remarks
 
 To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0501 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745).
 
-Examples
---------
+[!INCLUDE [no-vt-equiv-shell-banner](./includes/no-vt-equiv-shell-banner.md)]
+
+## Examples
 
 For an example, see [Console Aliases](console-aliases.md).
 
-Requirements
-------------
-
-<table>
-<colgroup>
-<col width="50%" />
-<col width="50%" />
-</colgroup>
-<tbody>
-<tr class="odd">
-<td><p>Minimum supported client</p></td>
-<td><p>Windows 2000 Professional [desktop apps only]</p></td>
-</tr>
-<tr class="even">
-<td><p>Minimum supported server</p></td>
-<td><p>Windows 2000 Server [desktop apps only]</p></td>
-</tr>
-<tr class="odd">
-<td><p>Header</p></td>
-<td>ConsoleApi3.h (via Wincon.h, include Windows.h)</td>
-</tr>
-<tr class="even">
-<td><p>Library</p></td>
-<td>Kernel32.lib</td>
-</tr>
-<tr class="odd">
-<td><p>DLL</p></td>
-<td>Kernel32.dll</td>
-</tr>
-<tr class="even">
-<td><p>Unicode and ANSI names</p></td>
-<td><p><strong>AddConsoleAliasW</strong> (Unicode) and <strong>AddConsoleAliasA</strong> (ANSI)</p></td>
-</tr>
-<tr class="odd">
-</tr>
-<tr class="even">
-</tr>
-<tr class="odd">
-</tr>
-<tr class="even">
-</tr>
-</tbody>
-</table>
-
-## <span id="see_also"></span>See also
+## Requirements
+
+| &nbsp; | &nbsp; |
+|-|-|
+| Minimum supported client | Windows 2000 Professional \[desktop apps only\] |
+| Minimum supported server | Windows 2000 Server \[desktop apps only\] |
+| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) |
+| Library | Kernel32.lib |
+| DLL | Kernel32.dll |
+| Unicode and ANSI names | **AddConsoleAliasW** (Unicode) and **AddConsoleAliasA** (ANSI) |
 
+## See also
 
 [Console Aliases](console-aliases.md)
 
@@ -135,11 +99,3 @@ Requirements
 [**GetConsoleAliases**](getconsolealiases.md)
 
 [**GetConsoleAliasExes**](getconsolealiasexes.md)
-
-
-
-
-
-
-
-
diff --git a/docs/allocconsole.md b/docs/allocconsole.md
@@ -33,30 +33,25 @@ api_type:
 
 # AllocConsole function
 
-
 Allocates a new console for the calling process.
 
-Syntax
-------
+## Syntax
 
 ```C
 BOOL WINAPI AllocConsole(void);
 ```
 
-Parameters
-----------
+## Parameters
 
 This function has no parameters.
 
-Return value
-------------
+## Return value
 
 If the function succeeds, the return value is nonzero.
 
 If the function fails, the return value is zero. To get extended error information, call [**GetLastError**](https://msdn.microsoft.com/library/windows/desktop/ms679360).
 
-Remarks
--------
+## Remarks
 
 A process can be associated with only one console, so the **AllocConsole** function fails if the calling process already has a console. A process can use the [**FreeConsole**](freeconsole.md) function to detach itself from its current console, then it can call **AllocConsole** to create a new console or [**AttachConsole**](attachconsole.md) to attach to another console.
 
@@ -66,46 +61,17 @@ If the calling process creates a child process, the child inherits the new conso
 
 This function is primarily used by a graphical user interface (GUI) application to create a console window. GUI applications are initialized without a console. Console applications are initialized with a console, unless they are created as detached processes (by calling the [**CreateProcess**](https://msdn.microsoft.com/library/windows/desktop/ms682425) function with the **DETACHED\_PROCESS** flag).
 
-Requirements
-------------
-
-<table>
-<colgroup>
-<col width="50%" />
-<col width="50%" />
-</colgroup>
-<tbody>
-<tr class="odd">
-<td><p>Minimum supported client</p></td>
-<td><p>Windows 2000 Professional [desktop apps only]</p></td>
-</tr>
-<tr class="even">
-<td><p>Minimum supported server</p></td>
-<td><p>Windows 2000 Server [desktop apps only]</p></td>
-</tr>
-<tr class="odd">
-<td><p>Header</p></td>
-<td>ConsoleApi3.h (via Wincon.h, include Windows.h)</td>
-</tr>
-<tr class="even">
-<td><p>Library</p></td>
-<td>Kernel32.lib</td>
-</tr>
-<tr class="odd">
-<td><p>DLL</p></td>
-<td>Kernel32.dll</td>
-</tr>
-<tr class="even">
-</tr>
-<tr class="odd">
-</tr>
-<tr class="even">
-</tr>
-</tbody>
-</table>
-
-## <span id="see_also"></span>See also
+## Requirements
+
+| &nbsp; | &nbsp; |
+|-|-|
+| Minimum supported client | Windows 2000 Professional \[desktop apps only\] |
+| Minimum supported server | Windows 2000 Server \[desktop apps only\] |
+| Header | ConsoleApi.h (via WinCon.h, include Windows.h) |
+| Library | Kernel32.lib |
+| DLL | Kernel32.dll |
 
+## See also
 
 [Console Functions](console-functions.md)
 
@@ -118,11 +84,3 @@ Requirements
 [**FreeConsole**](freeconsole.md)
 
 [**GetStdHandle**](getstdhandle.md)
-
- 
-
- 
-
-
-
-