wez/wezterm
1
1
Fork 0
mirror of https://github.com/wez/wezterm.git synced 2024-12-23 13:21:38 +03:00
Code Issues Projects Releases Wiki Activity

docs: for canonicalize_pasted_newlines changes

Browse Source 
refs: #1575
This commit is contained in:
Wez Furlong 2022-01-22 10:07:47 -07:00
parent bfe684151b
commit ebaa796b70
2 changed files with 27 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/changelog.md
View File

@ -33,6 +33,7 @@ As features stabilize some brief notes about them will accumulate here.
* `wezterm cli`, when run outside of a wezterm pane, now prefers to connect to the main GUI instance rather than background mux server. Use `wezterm cli --prefer-mux` to ignore the GUI instance and talk only to the mux server. See `wezterm cli --help` for additional information.
* [ScrollByPage](config/lua/keyassignment/ScrollByPage.md) now accepts fractional numbers like `0.5` to scroll by half a page at time. Thanks to [@hahuang65](https://github.com/hahuang65)! [#1534](https://github.com/wez/wezterm/pull/1534)
* [use_ime](config/lua/config/use_ime.md) now defaults to `true` on all platforms; previously it was not enabled by default on macOS.
* [canonicalize_pasted_newlines](config/lua/config/canonicalize_pasted_newlines.md) default has changed to be more compatible for `nano` users, and now provides more control over the text format that is pasted. [#1575](https://github.com/wez/wezterm/issues/1575)
#### Updated and Improved

52
docs/config/lua/config/canonicalize_pasted_newlines.md
View File

@ -2,39 +2,39 @@
*Since: 20211204-082213-a66c61ee9*
Controls whether pasted text will have newlines normalized to CRLF form.
Controls whether pasted text will have newlines normalized.
In general wezterm tries to stick with unix line endings as the one-true
representation because using canonical CRLF can result in excess blank lines
during a paste operation.
If bracketed paste mode is enabled by the application, the effective
value of this configuration option is `"None"`.
The following values are accepted:
|value|meaning|version|
|-----|-------|---------------|
|`true` |same as `"CarriageReturnAndLineFeed"`|*Since: 20211204-082213-a66c61ee9*|
|`false` |same as `"None"`|*Since: 20211204-082213-a66c61ee9*|
|`"None"` |The text is passed through unchanged|*Since: nightly builds only*|
|`"LineFeed"` |Newlines of any style are rewritten as LF|*Since: nightly builds only*|
|`"CarriageReturn"` |Newlines of any style are rewritten as CR|*Since: nightly builds only*|
|`"CarriageReturnAndLineFeed"` |Newlines of any style are rewritten as CRLF|*Since: nightly builds only*|
Note that the string forms of these values are accepted in nightly builds only,
however, `true` in all prior versions behaves the same way as
`"CarriageReturnAndLineFeed"` behaves in the nightly build.
The default value has changed in different versions of wezterm:
|version|platform|default|
|-------|--------|-------|
|20211204-082213-a66c61ee9|Windows|`"CarriageReturnAndLineFeed"`|
|20211204-082213-a66c61ee9|NOT Windows|`"None"`|
|nightly builds only|NOT Windows|`"CarriageReturn"`|
On Windows we're in a bit of a frustrating situation: pasting into
Windows console programs requires CRLF otherwise there is no newline
at all, but when in WSL, pasting with CRLF gives excess blank lines.
By default, when `canonicalize_pasted_newlines` is not set in your
configuration, if wezterm is running as a native Windows application, then the
effective value of this setting will be `true`, otherwise it will be false.
The behavior of this setting is:
* If bracketed paste mode is enabled by the application, this configuration has no effect on the pasted text
* Otherwise, if `canonicalize_line_endings == true`, then the line endings will be converted to `CRLF` form
In practice, the default setting means that unix shells and vim will get the
unix newlines in their pastes (which is the UX most users will want) and
cmd.exe will get CRLF.
However, it is an imperfect world: some users take great pains to only run
unixy programs from their Windows wezterm, which means that they end up with
CRLFs in places where they don't want them. Those users will likely wish to
set their configuration like this:
```lua
return {
-- I only ever run unix programs, even on my Windows system, so I always
-- want my pastes to use unix newlines.
canonicalize_pasted_newlines = false,
}
```