Let's document: PowerShell

[reinhart1010]

Sorry for the bad timing (it's the first day of Hacktoberfest 2021 so yeah), but I think documenting tldr pages for the Windows cross-platform PowerShell could be a great idea.

No, not the tldr page for windows/powershell, but all the PowerShell cmdlets like Get-Help, Invoke-WebRequest, Get-StartApps and so on.

These cmdlets uses a combination of kebab-case and (Upper) CamelCase, while according to the tldr-page guidelines all commands should be lowercase. So this could be a concern for contributors and clients.

Furthermore, some PowerShell cmdlets are only available for Windows, making the page structure slightly complicated. For example, curl often redirects to Invoke-WebRequest when used in Windows where the actual curl is not installed. Note that both curl and Invoke-WebRequest are completely different commands with different parameters and options.

[reinhart1010]

Okay, I've seen that the Get-Content PowerShell command is also documented in windows/get-content, and the command also works in my Linux installation of PowerShell, too!

[sbrl]

Hey there! Thanks for opening this issue. Hmm, I think we want a few opinions on this.

It would be easy if powershell was windows-specific (though I can imagine Windows accounts for the majority of powershell usage anyway), but as you say powershell is cross-platform.

Perhaps documenting in common would work - so long as any commands documented are clearly labelled as powershell commands rather then ordinary commands that work in a regular shell.

Let's wait for some more opinions from people on this before making a decision.

[marchersimon]

We probably won't have any name collisions, but even though it's available on all platforms it will be used on Windows most of the time. Not directly comparable, but still: we also don't put Linux commands under common because it's available through WSL.

[reinhart1010]

I was thinking to simply put all PowerShell documentation into powershell/, and some Windows-only commands will have this notice:

This command works only on Windows

or (Windows Server-specific)

This command works only on Windows Server

[marchersimon]

I don't think we should really add a new platform for PowerShell. I think putting all PowerShell pages into windows/ makes the most sense.

[sbrl]

Yeah, I agree @marchersimon. The windows platform makes the most sense here.

[sbrl]

Ref "This command works only on Windows", I would suggest that the better solution here would be a platform-specific copy of the page in the respective platform folder. For example, if blah has some common functionality but also some windows-specific functionality, then we would have copies of the page under common/blah and windows/blah, with the Windows-specific functionality being documented under windows/blah only.

[tayopi]

I'd love to help with this since PowerShell is my primary shell. I had a question about documentation though. For commandlets like Get-ChildItem, there are built in aliases (e.g. dir, gci, ls) These were included by Microsoft to make life easier for users who are more familiar with shells like Command Prompt on Windows or bash. I think these are helpful, but I don't know the best way to document them or if they should be documented at all.

[reinhart1010]

There is a standard template for writing alias documentation, see https://github.com/tldr-pages/tldr/blob/main/contributing-guides/translation-templates/alias-pages.md. But there are some edge cases like Invoke-WebRequest with curl and wget, like on #8177.

For Command Prompt aliases in PowerShell, as long as the PowerShell version accepts the traditional Command Prompt parameters, I think it’s OK to add something like:

In PowerShell, this command is an alias of {{PowerShell-Command}} which also supports the following Command Prompt (cmd.exe) commands.

[sbrl]

#11227 has implemented the issues discussed here. However, it seems that #11298 has put PowerShell commands in the wrong place (common/ instead of windows/), unless I'm confused?

/cc @kbdharun, @sebastiaanspeck?

[kbdharun]

#11227 has implemented the issues discussed here. However, it seems that #11298 has put PowerShell commands in the wrong place (common/ instead of windows/), unless I'm confused?

/cc @kbdharun, @sebastiaanspeck?

It's intentional I think, some powershell commands are cross platform, whereas most are Windows specific.

[sbrl]

Ahhh okayt @kbdharun. Thanks for the clarification. So long as PowerShell commands are clearly labelled, I see no issue with this. In which case, I'm going to close this issue for now given we've all agreed.

I'd suggest that any lists of PowerShell commands to document should be a separate issue to keep them clean.

We can always re-open if there's more to discuss.