Documentation for DISABLE_NEWLINE_AUTO_RETURN is wrong

[alexrp]

See: microsoft/terminal#4126 (comment)

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 34ea4fba-5919-fff6-9941-f213a557c651
• Version Independent ID: 5c22080b-6969-4721-5e5c-40c348680701
• Content: SetConsoleMode function - Windows Console
• Content Source: docs/setconsolemode.md
• Product: console
• GitHub Login: @bitcrazed
• Microsoft Alias: richturn

[pizzaz93]

https://github.com/MicrosoftDocs/Console-Docs/blob/main/docs/includes/console-mode-flags.md is the source file, drafting some potential content here to update the documentation to more accurately reflect the flag behavior.

DISABLE_NEWLINE_AUTO_RETURN: When writing with WriteFile or WriteConsole, this prevents the cursor from automatically moving to the next line when text reaches the end of the line. The written character will be printed in the final position on the line and the cursor will remain above this character as if ENABLE_WRAP_AT_EOL_OUTPUT was off, but the next printable character will be printed as if ENABLE_WRAP_AT_EOL_OUTPUT is on. No overwrite will occur. Specifically, the cursor quickly advances down to the following line, a scroll is performed if necessary, the character is printed, and the cursor advances one more position.

The typical usage of this flag is intended in conjunction with setting ENABLE_VIRTUAL_TERMINAL_PROCESSING to better emulate a terminal emulator where writing the final character on the screen (../in the bottom right corner) without triggering an immediate scroll is the desired behavior.

ENABLE_VIRTUAL_TERMINAL_PROCESSING
When writing with WriteFile or WriteConsole, characters are parsed for VT100 and similar control character sequences that control cursor movement, color/font mode, and other operations that can also be performed via the existing Console APIs. For more information, see Console Virtual Terminal Sequences.

Additionally this adds an additional state to end-of-line wrapping that can delay the cursor move and buffer scroll operations. Normally when ENABLE_WRAP_AT_EOL_OUTPUT is set and text reaches the end of the line, the cursor will immediately move to the next line and the contents of the buffer will scroll up by one line. In contrast with this flag set, the scroll operation and cursor move is delayed until the next character arrives.

@j4james would this content be more correct/align with the flag functions?

[j4james]

I think the ENABLE_VIRTUAL_TERMINAL_PROCESSING description sounds good, but the DISABLE_NEWLINE_AUTO_RETURN description is still wrong.

Usually when you output a linefeed character (U+000A), the cursor is moved down a line, and also moved across to the leftmost column (essentially executing a carriage return). However, when the DISABLE_NEWLINE_AUTO_RETURN mode is set, that carriage return step is skipped. The cursor moves down a line, but remains in the same column it started from.

[pizzaz93]

Thank you @j4james, I worked on incorporating that clarification into the document's pull request.

[pizzaz93]

@j4james does the associated PR look correct?

cc: @DHowett

[j4james]

@pizzaz93 The changes to ENABLE_VIRTUAL_TERMINAL_PROCESSING look good to me, but the description of the DISABLE_NEWLINE_AUTO_RETURN flag is still not quite right.

It doesn't have anything to do with ENABLE_WRAP_AT_EOL_OUTPUT or what happens when text reaches the end of the line. It's also got nothing to do with writing a character in the bottom right corner without trigger a scroll. All it effects is the behavior of the linefeed control character (U+000A) the way I explained in the comment above.

[pizzaz93]

@j4james I edited the text to more closely align with documenting that behavior, does this look correct?

Should the second paragraph be removed entirely?

| DISABLE_NEWLINE_AUTO_RETURN 0x0008 | When writing with WriteFile or WriteConsole, this flag changes end-of-line behavior. Normally when a linefeed character is outputted (U+000A), the cursor will immediately move to the next line and also move across to the leftmost column (carriage return). In contrast with this flag set, the carriage return is skipped, the cursor moves down a line, but remains in the same column it started from.

The typical usage of this flag is intended in conjunction with setting ENABLE_VIRTUAL_TERMINAL_PROCESSING to better emulate a terminal emulator where writing the final character on the screen (../in the bottom right corner) without triggering an immediate scroll is the desired behavior. |

[j4james]

Yeah. The second paragraph should be removed entirely.

[pizzaz93]

@DHowett or @zadjii-msft, I've implemented @j4james's feedback would you be able to review the referenced PR?

[alexrp]

I'd completely forgotten about this and it just bit us over at vezel-dev/cathode#156. Would be good if we could get this very wrong documentation corrected. It's a bit discouraging to see that #262 went ignored...

[avih]

The highly misleading docs issue about DISABLE_NEWLINE_AUTO_RETURN is known since 2020, and yet the docs are still not fixed - https://github.com/MicrosoftDocs/Console-Docs/blob/main/docs/includes/console-mode-flags.md and also not at the "real" docs site - https://learn.microsoft.com/en-us/windows/console/setconsolemode .

Please fix the docs. The console is complex enough on its own. Highly misleading docs don't help...

Also, as far as I can tell from my own testing, it seems that ENABLE_VIRTUAL_TERMINAL_PROCESSING also does what the wrong DISABLE_NEWLINE_AUTO_RETURN docs still say, and also make the console ignore the ENABLE_WRAP_AT_EOL_OUTPUT bit.

I.e. when VT is enabled it also enables the "additional state at EOL where the cursor stays once at the last column, and another char will then make it wrap" (to prevent scroll etc), and it's impossible to disable wrap-at-eol, and it's also impossible to disable auto-return.

I don't think it's necessarily a bad thing, but it would be nice to have it documented.