diff --git a/docs/KNOWNISSUES.md b/docs/KNOWNISSUES.md index cb111f071..23b72515c 100644 --- a/docs/KNOWNISSUES.md +++ b/docs/KNOWNISSUES.md @@ -1,5 +1,5 @@ -Known Issues with the first PowerShell on Linux Alpha Release -========================================================== +Known Issues for PowerShell on Linux +==================================== The first Alpha release of PowerShell on Linux is mostly functional but does have some significant limitations and usability issues. In some @@ -36,18 +36,18 @@ of ways, obvious and non-obvious. .PS1 File Extensions -------------------- -PowerShell scripts must end in ".ps1" for the interpreter to understand +PowerShell scripts must end in `.ps1` for the interpreter to understand how to load and run them in the current process. Running scripts in the -current process is the expected usual behavior for PowerShell. The "#!" -magic number may be added to a script that doesn't have a .ps1 extension +current process is the expected usual behavior for PowerShell. The `#!` +magic number may be added to a script that doesn't have a `.ps1` extension, but this will cause the script to be run in a new PowerShell instance preventing the script from working properly when interchanging objects. Missing command aliases ----------------------- -On the, the "convenience aliases" for the basic commands "ls", "cp", -"mv", "rm", "cat", "man", "mount", "ps" have been removed. On Windows, +On the, the "convenience aliases" for the basic commands `ls`, `cp`, +`mv`, `rm`, `cat`, `man`, `mount`, `ps` have been removed. On Windows, PowerShell provides a set of aliases that map to UNIX/Linux command names for user convenience. These aliases have been removed from the default PowerShell on Linux distribution, allowing the native executable to @@ -59,17 +59,17 @@ not objects. > NOTE: This is an area where the PowerShell team is looking for feedback. > What is the preferred solution? Should we leave it as is or add the > convenience aliases back? See -> [Issue 929](https://github.com/PowerShell/PowerShell/issues/929 "Issue 929") +> [Issue #929](https://github.com/PowerShell/PowerShell/issues/929). Missing Wildcard (globbing) Support ------------------------------------ Currently, PowerShell only does wildcard expansion (globbing) for the built-ins but not for external commands. This means that a command like -"ls \*.txt" will fail because the asterisk will not be expanded to match -file names. You can work around this by doing "ls (gci \*.txt | % name)" -or, more simply, "gci \*.txt" using the PowerShell built-in equivalent -to ls. +`ls *.txt` will fail because the asterisk will not be expanded to match +file names. You can work around this by doing `ls (gci *.txt | % name)` +or, more simply, `gci *.txt` using the PowerShell built-in equivalent +to `ls`. .NET Framework vs .NET Core Framework ----------------- @@ -85,7 +85,7 @@ Redirection Issues ------------------ Input redirection is not supported in PowerShell on any platform. Use -either "cat" or "Get-Content" to write the contents of a file into the +either `Get-Content` to write the contents of a file into the pipeline. PowerShell does not currently support "direct pipelining" external @@ -95,16 +95,17 @@ command in the pipeline is run to completion and then the aggregated data is passed to the next command. (This behavior is intended to be fixed in a later release.) -Redirected output will contain a Byte-order Mark (BOM) when the default +Redirected output will contain the Unicode byte order mark (BOM) when the default UTF-8 encoding is used. The BOM will cause problems when working with utilities that do not expect it or when appending to a file. +Use `-Encoding ascii` to write ASCII text (which, not being Unicode, will not have a BOM). + Job Control ----------- -There is no job-control support in PowerShell on Linux. The fg and bg -commands are not available. Ctrl-Z works but the commands cannot be -brought into the foreground. +There is no job-control support in PowerShell on Linux. The `fg` and `bg` commands are not available. +`Ctrl-Z` sends the `powershell` process to the background. Remoting Support ---------------- @@ -126,11 +127,12 @@ sudo, exec and PowerShell Because PowerShell runs most commands in memory (like Python or Ruby) you can't use sudo directly with PowerShell built-ins. (You can, of -course, run powershell.exe from sudo.) If it is necessary to run a -PowerShell cmdlet from within PowerShell with sudo, for example "sudo -Set-Date 8/18/2016", then you would do "sudo powershell Set-Date 8/18/2016". +course, run `powershell` from sudo.) If it is necessary to run a +PowerShell cmdlet from within PowerShell with sudo, +for example `sudo Set-Date 8/18/2016`, +then you would do `sudo powershell Set-Date 8/18/2016`. Likewise, you can't exec a PowerShell built-in -directly. Instead you would have to do "exec powershell item\_to\_exec". +directly. Instead you would have to do `exec powershell item_to_exec`. Missing Cmdlets --------------- @@ -153,40 +155,41 @@ PowerShell.