Add documentation for configuring encoding with VSCode and PowerShell #3743
Conversation
|
OPS Build status updates of commit 5c4dbec: 🕙 Preparing: average preparing time is 1 min(s) 9 sec(s) |
|
OPS Build status updates of commit 5c4dbec: 🕙 Incremental building: average incremental building time is 12 min(s) 47 sec(s) |
|
OPS Build status updates of commit 5c4dbec: ✅ Validation status: passed
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
|
OPS Build status updates of commit df461d8: 🕙 Preparing: average preparing time is 1 min(s) 9 sec(s) |
|
OPS Build status updates of commit df461d8: 🕙 Incremental building: average incremental building time is 12 min(s) 48 sec(s) |
|
OPS Build status updates of commit df461d8: ✅ Validation status: passed
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
|
Yeah, looks good to me, thanks Rob! |
|
OPS Build status updates of commit 312d081: 🕙 Preparing: average preparing time is 1 min(s) 9 sec(s) |
|
OPS Build status updates of commit 312d081: 🕙 Incremental building: average incremental building time is 12 min(s) 48 sec(s) |
|
OPS Build status updates of commit 312d081: ✅ Validation status: passed
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
|
@rjmholt I need to do some major edits for style, etc. I will update the PR and ask you to review. |
sdwheeler
force-pushed
the
vscode-encoding
branch
from
312d081 to
603c928
Compare
|
OPS Build status updates of commit 603c928: 🕙 Preparing: average preparing time is 1 min(s) 9 sec(s) |
|
OPS Build status updates of commit 603c928: 🕙 Incremental building: average incremental building time is 12 min(s) 49 sec(s) |
|
@rjmholt @TylerLeonhardt Please review my changes to this PR. |
|
OPS Build status updates of commit 603c928: ✅ Validation status: passed
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
|
OPS Build status updates of commit 53034a0: 🕙 Preparing: average preparing time is 1 min(s) 9 sec(s) |
|
OPS Build status updates of commit 53034a0: 🕙 Incremental building: average incremental building time is 12 min(s) 50 sec(s) |
|
OPS Build status updates of commit 53034a0: ✅ Validation status: passed
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
|
OPS Build status updates of commit 0a7cdc4: 🕙 Preparing: average preparing time is 1 min(s) 9 sec(s) |
|
OPS Build status updates of commit 0a7cdc4: 🕙 Incremental building: average incremental building time is 12 min(s) 50 sec(s) |
|
OPS Build status updates of commit 0a7cdc4: ✅ Validation status: passed
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
|
|
||
| When using VS Code to create and edit PowerShell scripts, it is important that your files are saved | ||
| using the correct character encoding format. | ||
|
|
There was a problem hiding this comment.
I think we still need a shortcut section at the top of some kind, if only a link to the recommended settings in the other doc.
Otherwise I think people aren't going to read the whole thing and will just keep opening issues in the vscode-PowerShell repo.
There was a problem hiding this comment.
Look at the preview rendering of the article. All H2 appear in the right-nav panel. Very easy to jump to the configuration header. Also, an abbreviated version of this is in the using-vscode.md article.
| extension falls back to loading that script's content from the file system. VSCode defaults to | ||
| UTF-8 encoding, but uses [byte-order mark][], or BOM, detection to select the correct encoding. | ||
|
|
||
| The problem occurs when assuming the encoding of BOM-less formats (like [UTF-8] with no BOM and [Windows-1252]). |
There was a problem hiding this comment.
The linking to UTF-8 and Windows-1252 seems inconsistent. I think it should either be a link in the first instance or a link everywhere. Certainly we need to have some discoverable way to explain what is meant by UTF-8 and Windows-1252.
There was a problem hiding this comment.
Should be first mention. I will fix it.
|
|
||
| In the Linux world, on the web, and in .NET Standard, UTF-8 is now the dominant encoding. | ||
|
|
||
| Unicode encodings also have the concept of a byte-order mark (BOM). BOMs occur at the beginning of |
There was a problem hiding this comment.
byte-order mark should be a link here, since this paragraph explains the concept
There was a problem hiding this comment.
It is already a link at first mention. Do we want to move this content up?
There was a problem hiding this comment.
Didn't want to front-load the concept. We can leave for now I think
| Choosing an encoding depends on the platforms and applications you use to read and write your | ||
| PowerShell files. | ||
|
|
||
| On Windows, many applications have long used [Windows-1252]. Many .NET applications use [UTF-16], |
There was a problem hiding this comment.
This paragraph now seems fragmented and should be merged with the one below. It might be better as a series of points:
Different systems and applications tend to use different encodings:
- In .NET Standard, on the web and in the Linux world, [UTF-8][] is now the dominant encoding.
- Many .NET Framework applications use [UTF-16][]. For historical reasons, this is sometimes called "Unicode" in the .NET ecosystem, a term that now refers to a broad [standard](https://en.wikipedia.org/wiki/Unicode) including both UTF-8 and UTF-16.
- On Windows, many native applications predating Unicode continue to use [Windows-1252][] by default.
There was a problem hiding this comment.
@joeyaiello made the good point that the Unicode term is mainly used in .NET.
It's important because of the [System.Text.Encoding]::Unicode enum value and the Get-Content -Encoding Unicode parameter value, which both refer to UTF-16. We have to say "Unicode", but don't want people to think they want to use the "Unicode" encoding.
There was a problem hiding this comment.
Used your bulleted list.
| to be bytes that rarely occur in non-Unicode text, allowing a reasonable guess that text is Unicode | ||
| when a BOM is present. | ||
|
|
||
| BOMs are optional and their adoption isn't as popular in the Linux world because a dependable |
There was a problem hiding this comment.
Should be either because of or is used
| ``` | ||
|
|
||
| The following [this script](https://gist.github.com/rjmholt/3d8dd4849f718c914132ce3c5b278e0e) can be | ||
| used to determine what encoded your PowerShell session infers for a script without a BOM. |
There was a problem hiding this comment.
| used to determine what encoded your PowerShell session infers for a script without a BOM. | |
| used to determine what encoding your PowerShell session infers for a script without a BOM: |
| ### Scripts | ||
|
|
||
| Scripts already on the file system may need to be re-encoded to your new chosen encoding. In the | ||
| bottom bar of VSCode, you'll see the label UTF-8. Click it to open the action bar and select |
There was a problem hiding this comment.
I would also keep the link to something visual with this information. I always find GUI instructions impossible to follow
There was a problem hiding this comment.
Added link to vscode docs
| ## What is file encoding and why is it important? | ||
|
|
||
| VSCode manages the interface between a human entering strings of characters into a buffer and | ||
| reading/writing blocks of bytes to the filesystem. When VSCode saves the file, it uses a text |
There was a problem hiding this comment.
| reading/writing blocks of bytes to the filesystem. When VSCode saves the file, it uses a text | |
| reading/writing blocks of bytes to the filesystem. When VSCode saves a file, it uses a text |
| 2. When scripts are executed directly in the Integrated Console, they're read from the file by | ||
| PowerShell directly. Tf PowerShell's encoding differs from VSCode's, something can go wrong here. | ||
| 3. When a script that is open in VSCode references another script that is not open in VSCode, the | ||
| extension falls back to loading that script's content from the file system. VSCode defaults to |
There was a problem hiding this comment.
The last sentence here needs to refer to the extension, not VSCode. PowerShell Editor Services loads the file in this case, and also does BOM detection.
It's an important distinction since many of our users don't know where the line ends between VSCode and the PowerShell extension.
There was a problem hiding this comment.
OK. It was unclear to me as well. Fixed
There was a problem hiding this comment.
It's an unfortunately complicated architecture, made worse by the fact that the PowerShell extension doesn't have a nice name to differentiate itself as a component
| VSCode's default encoding is UTF-8 without BOM. | ||
|
|
||
| To set [VSCode's encoding](https://code.visualstudio.com/docs/editor/codebasics#_file-encoding-support), | ||
| go to the VSCode settings (Ctrl+,) and set the `"files.encoding"` setting: |
There was a problem hiding this comment.
The key chords should still be emphasised in some way. If the <kbd> tags are unacceptable, the VSCode docs use monospace spans.
There was a problem hiding this comment.
I had some back-and-forth about this. We try to minimize inline HTML tags but this one is valuable. Restored the kbd tags.
There was a problem hiding this comment.
They're the only tags I use in markdown -- hopefully it will get a native syntax eventually
|
OPS Build status updates of commit 0aa9bbe: 🕙 Preparing: average preparing time is 1 min(s) 9 sec(s) |
|
OPS Build status updates of commit 0aa9bbe: 🕙 Incremental building: average incremental building time is 12 min(s) 50 sec(s) |
There was a problem hiding this comment.
I can't approve my own PR, but LGTM -- just needs that last suggestion change I think (I tagged you @sdwheeler)
|
OPS Build status updates of commit 0aa9bbe: ✅ Validation status: passed
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
|
OPS Build status updates of commit 2cfd5c9: 🕙 Preparing: average preparing time is 1 min(s) 9 sec(s) |
|
OPS Build status updates of commit 2cfd5c9: 🕙 Incremental building: average incremental building time is 12 min(s) 50 sec(s) |
|
@rjmholt I fixed that last item you tagged. Waiting for build to finish. Thanks. |
|
OPS Build status updates of commit 2cfd5c9: ✅ Validation status: passed
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
From PowerShell/vscode-powershell#1761.
Version(s) of document impacted
Reason(s) for not updating all version of documents