From 7c88bf3996f8ca101174ad839b8a623df0e469bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleksandar=20Nikoli=C4=87?= Date: Thu, 18 Aug 2016 06:17:06 +0200 Subject: [PATCH] fix typos and casing in KNOWNISSUES.md (#1860) Fix typos and casing. "on Linux PowerShell" change to "in PowerShell on Linux". Apply "one-sentence-per-line" rule. --- docs/KNOWNISSUES.md | 132 +++++++++++++++++++++----------------------- 1 file changed, 62 insertions(+), 70 deletions(-) diff --git a/docs/KNOWNISSUES.md b/docs/KNOWNISSUES.md index 23b72515c4..0d1c1b3d73 100644 --- a/docs/KNOWNISSUES.md +++ b/docs/KNOWNISSUES.md @@ -2,59 +2,58 @@ 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 -cases, these issues are simply bugs that haven't been fixed yet. In -other cases (as with the default aliases for ls, cp, etc.) we are +does have some significant limitations and usability issues. +In some cases, these issues are simply bugs that haven't been fixed yet. +In other cases (as with the default aliases for ls, cp, etc.) we are looking for feedback from the community regarding the choices we make. -Case-sensitivity in PowerShell. +Case-sensitivity in PowerShell ------------------------------- -Historically PowerShell has uniformly been case-insensitive. On UNIX, -the file system is case-sensitive and this is exposed through a number +Historically, PowerShell has uniformly been case-insensitive. +On UNIX, the file system is case-sensitive and this is exposed through a number of ways, obvious and non-obvious. ### Directly: - When specifying a file in PowerShell the correct case must be used. -- Only forward slashes can be used in path. (On Windows either forward - or backward slashes can be used.) +- Only forward slashes can be used in path. + (On Windows either forward or backward slashes can be used.) ### Indirectly: - If a script tries to load a module and the module name is not cased - correctly, then the module load will fail. This may cause a problem - with existing scripts if the name by which the module is referenced + correctly, then the module load will fail. + This may cause a problem with existing scripts if the name by which the module is referenced doesn't match the actual file name. -- Tab-completion will not automatically auto-complete if the file name - case is wrong. The fragment to complete must be cased properly. - (Completion is case-insensitive for type name and type - member completions.) +- Tab-completion will not automatically auto-complete if the file name case is wrong. + The fragment to complete must be cased properly. + (Completion is case-insensitive for type name and type member completions.) .PS1 File Extensions -------------------- 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, +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, 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, -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 -be run instead. There are pros and cons to having do this. It exposes -the native command experience to the PowerShell on Linux user but reduces -functionality in the shell because the native commands return strings -not objects. +On Linux, 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 be run instead. +There are pros and cons to having do this. +It exposes the native command experience to the PowerShell on Linux user but reduces +functionality in the shell because the native commands return strings 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 @@ -65,91 +64,84 @@ 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`. +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`. .NET Framework vs .NET Core Framework ----------------- PowerShell on Linux uses the .NET Core which is a subset of the full -.NET framework on Microsoft Windows. This is significant because -PowerShell provides direct access to the underlying framework types, -methods etc. As a result, scripts that run on Windows may not run on -Linux because of the differences in the frameworks. For more information -about .NET Core framework, see +.NET Framework on Microsoft Windows. +This is significant because PowerShell provides direct access to the underlying framework types, +methods etc. +As a result, scripts that run on Windows may not run on Linux because of the differences in the frameworks. +For more information about .NET Core Framework, see Redirection Issues ------------------ -Input redirection is not supported in PowerShell on any platform. Use -either `Get-Content` to write the contents of a file into the -pipeline. +Input redirection is not supported in PowerShell on any platform. +Use either `Get-Content` to write the contents of a file into the pipeline. -PowerShell does not currently support "direct pipelining" external -commands. Although the pipeline works properly for built-in PowerShell -commands, with external (also called native) commands, each individual +PowerShell does not currently support "direct pipelining" external commands. +Although the pipeline works properly for built-in PowerShell commands, +with external (also called native) commands, each individual 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.) +data is passed to the next command. +(This behavior is intended to be fixed in a later release.) -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. +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. +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 ---------------- -Client-side remoting from Linux is not supported with the initial -package. This will be enabled shortly after the Alpha release by -installing an additional package. +Client-side remoting from Linux is not supported with the initial package. +This will be enabled shortly after the Alpha release by installing an additional package. Just-Enough-Administration (JEA) Support ---------------------------------------- The ability to create constrained administration (JEA) remoting -endpoints is not currently available in PowerShell on Linux. This -feature will be enabled shortly after the Alpha release by installing -new package. +endpoints is not currently available in PowerShell on Linux. +This feature will be enabled shortly after the Alpha release by installing new package. -sudo, exec and PowerShell +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` from sudo.) If it is necessary to run a -PowerShell cmdlet from within PowerShell with sudo, +you can't use sudo directly with PowerShell built-ins. +(You can, of 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`. +Likewise, you can't exec a PowerShell built-in directly. +Instead you would have to do `exec powershell item_to_exec`. Missing Cmdlets --------------- -A large number of the commands (cmdlets) normally available in -PowerShell are not available on Linux. In many cases, these commands -make no sense on Linux (e.g. Windows-specific features like the -registry). Other commands like the service control commands -(get/start/stop-service are present but not functional.) Future releases -will correct these problems, fixing the broken cmdlets and adding new -ones over time. +A large number of the commands (cmdlets) normally available in PowerShell are not available on Linux. +In many cases, these commands make no sense on Linux (e.g. Windows-specific features like the registry). +Other commands like the service control commands (get/start/stop-service are present but not functional.) +Future releases will correct these problems, fixing the broken cmdlets and adding new ones over time. Command Availability -------------------- -The following table lists commands that are known not to work on Linux -PowerShell. +The following table lists commands that are known not to work in PowerShell on Linux. -
CommandsOperational StateNotes @@ -193,7 +185,7 @@ PowerShell. Returns a message saying not supported on this platform. Execution policy is a user-focused "safety belt" that helps prevent the user from making expensive mistakes. It is not a security boundary.
Select-XML +Select-Xml Available but doesn't work. The underlying Select.Xml.Node classes are missing on Linux/.NET Core. This is unlikely to be fixed in the near term so this cmdlet will be probably be removed.