Repository navigation
Closed
Labels
Resolution-No ActivityIssue has had no activity for 6 months or moreIssue has had no activity for 6 months or moreUp-for-GrabsUp-for-grabs issues are not high priorities, and may be opportunities for external contributorsUp-for-grabs issues are not high priorities, and may be opportunities for external contributorsWG-Interactive-HelpSystemhelp infrastructure and formatting of helphelp infrastructure and formatting of help
Description
Prerequisites
- Write a descriptive title.
- Make sure you are able to repro it on the latest released version
- Search the existing issues.
- Refer to the FAQ.
- Refer to Differences between Windows PowerShell 5.1 and PowerShell.
Steps to reproduce
I am writing a PowerShell module and adding help text for each of my exported cmdlets.
Several of my commands include multi-line examples, showing the command usage and example output, e.g.:
.EXAMPLE
PS> $devices = Get-MTPDeviceList
PS> if ($devices) { $devices[0].Name }
"My Phone"
.EXAMPLE
# Some explanatory text about the example.
PS> Get-MTPDeviceList
Name Type
---- ----
Some Phone Mobile Phone
I have tested my module in both Visual Studio Code's PowerShell terminal and also a separate instance of PowerShell in Terminal. When calling Get-Help Get-MTPDeviceList with switches that show example text (e.g. -Full or -Examples), the formatting of the displayed examples text is incorrect.
Specifically:
- Any leading spaces between the "PS>" and the rest of the string on the first line is removed.
- If the first line of an example is a comment (with or without a leading
#), the text "PS >" is inserted before it.
Expected behavior
The following output should be displayed in the examples section when Get-Help -Full is called:
-------------------------- EXAMPLE 1 --------------------------
PS> $devices = Get-MTPDeviceList
PS> if ($devices) { $devices[0].Name }
"My Phone"
-------------------------- EXAMPLE 2 --------------------------
# Some explanatory text about the example.
PS> Get-MTPDeviceList
Name Type
---- ----
Some Phone Mobile PhoneActual behavior
The following is output. Note the removal of the space character in the first line of the first example and the insertion of the text "PS >" in the first line of the second example.
-------------------------- EXAMPLE 1 --------------------------
PS>$devices = Get-MTPDeviceList
PS> if ($devices) { $devices[0].Name }
"My Phone"
-------------------------- EXAMPLE 2 --------------------------
PS > # Some explanatory text about the example.
PS> Get-MTPDeviceList
Name Type
---- ----
Some Phone Mobile PhoneError details
No response
Environment data
Name Value
---- -----
PSVersion 7.4.2
PSEdition Core
GitCommitId 7.4.2
OS Microsoft Windows 10.0.22631
Platform Win32NT
PSCompatibleVersions {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion 2.3
SerializationVersion 1.1.0.1
WSManStackVersion 3.0Visuals
No response
Metadata
Metadata
Assignees
Labels
Resolution-No ActivityIssue has had no activity for 6 months or moreIssue has had no activity for 6 months or moreUp-for-GrabsUp-for-grabs issues are not high priorities, and may be opportunities for external contributorsUp-for-grabs issues are not high priorities, and may be opportunities for external contributorsWG-Interactive-HelpSystemhelp infrastructure and formatting of helphelp infrastructure and formatting of help
Activity
237dmitry commentedon May 18, 2024
I do not view
PS>in cmdlet's help examples...As a workaround you can use
`u{2800}instead of`u{0020}daverayment commentedon May 18, 2024
237dmitry Your examples do not correspond to the details I provided in the Steps to Reproduce section above. The specific text formatting is significant, otherwise the issue will not present itself.
I can provide cut-down versions of the .psm1 and .psd1 files I am using, if that would help.
mklement0 commentedon May 18, 2024
237dmitry, the issue is about comment-based help, whereas built-in cmdlets come with external, MAML-based help files (though the discrepancy in the resulting behavior is surprising).
Dave Rayment (@daverayment):
Here's how things currently work:
The first line - only - after
.EXAMPLEis assumed to be the example command, and it is prefixed withPS >by default - even if you try to provide a comment as the first line.If you try to provide your own prefix, PowerShell retains it, but without preserving whitespace after
>- I'd say that's a bug.Anything after the first line is retained as-is.
Thus:
Place comments describing the example after the first line (and after a line showing sample output).
If you're not happy with the automatically applied
PS >prefix (which you'd have to replicate explicitly in subsequent lines): As a workaround for the bug, you can use 237dmitry's suggestion to embed a literal[char] 0x2800in lieu of space(s) after the>: this character will render like a space in terminals, but won't be trimmed by PowerShell.237dmitry commentedon May 18, 2024
I tried simple function and it reproduces your issue. Workaround:
daverayment commentedon May 19, 2024
Thank you both.
The workaround from 237dmitry does not work for me without using the special Unicode character for the space; otherwise, any spaces are removed. So:
PS>Somethinginstead of:
PS> SomethingThe default behaviour, as detailed by Michael Klement (@mklement0), is problematic for a number of reasons:
PS >is inconsistent with the in-built cmdlet's examples, which are all presented un-prefixed.PS >conflicts directly with all the examples on Microsoft's about Comment Based Help help page. All the examples in that guide havePS>present as prefixes to each of the example commands. Note the lack of space between thePSand>. This is the guide I followed when creating my own function's documentation.All we get for a header is the example number, e.g.
-----EXAMPLE 1-----. We should be able to produce help documentation which is consistent with that for the built-in cmdlets.The whitespace-eating bug is annoying. I'm not keen on embedding special characters to get around this issue, but appreciate the advice. The other option is to leave out the
PS>prefix on the first line and rely on Get-Help adding the prefix itself for that line only, but again, this feels like a workaround for something which should not be happening. If MS change things around to remove the auto-addition of the prefix (which I hope they do!), this would again introduce inconsistency between the first line and subsequent ones if this workaround had been applied.In conclusion, I think a reasonable expectation from running
Get-Helpis that the comments are reproduced verbatim, with any formatting introduced by the cmdlet being merely cosmetic, such as the section headers. This is especially important for sections which include code.For this reason, I think the
PS >prefix should not be auto-added in future versions.If the prefix remains in future versions, it should obviously be documented, and not left as a surprise for the developer 😀
krzydoug commentedon May 23, 2024
I always wondered why there wasn't a way to add additional details after
.EXAMPLE. That'd be niceWishful thinking
theJasonHelmick commentedon May 29, 2024
Thank you Dave Rayment (@daverayment) for this issue. The Interactive working group had reviewed this and agrees there is a bug in the comment based help causing the space.
mklement0 commentedon Jun 19, 2024
As for the desire to be able to specify custom titles for each
.EXAMPLEsection, see:microsoft-github-policy-service commentedon Dec 17, 2024
This issue has not had any activity in 6 months, if there is no further activity in 7 days, the issue will be closed automatically.
Activity in this case refers only to comments on the issue. If the issue is closed and you are the author, you can re-open the issue using the button below. Please add more information to be considered during retriage. If you are not the author but the issue is impacting you after it has been closed, please submit a new issue with updated details and a link to this issue and the original.