Skip to content

Get-Help shows incorrect spacing and unwanted prefixes for first line of .EXAMPLE text #23814

Closed

Description

Prerequisites

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:

  1. Any leading spaces between the "PS>" and the rest of the string on the first line is removed.
  2. 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 Phone

Actual 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 Phone

Error 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.0

Visuals

No response

Activity

  1. 237dmitry commented on May 18, 2024

    @237dmitry

    I do not view PS> in cmdlet's help examples...

    ------------- Example 1: Get the current directory ------------
    
    Get-Item .
    
    Directory: C:\
    
    Mode                LastWriteTime     Length Name
    ----                -------------     ------ ----
    d----         7/26/2006  10:01 AM            ps-test
    
    
    ---- Example 2: Get all the items in the current directory ----
    
    Get-Item *
    
    Directory: C:\ps-test
    
    Mode                LastWriteTime     Length Name
    ----                -------------     ------ ----
    d----         7/26/2006   9:29 AM            Logs
    d----         7/26/2006   9:26 AM            Recs
    -a---         7/26/2006   9:28 AM         80 date.csv
    -a---         7/26/2006  10:01 AM         30 filenoext
    -a---         7/26/2006   9:30 AM      11472 process.doc
    -a---         7/14/2006  10:47 AM         30 test.txt
    
    
    ------- Example 3: Get the current directory of a drive -------
    
    Get-Item C:
    
    # and so on
    

    As a workaround you can use `u{2800} instead of `u{0020}

  2. daverayment commented on May 18, 2024

    @daverayment
    Author

    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.

  3. mklement0 commented on May 18, 2024

    @mklement0
    Contributor

    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 .EXAMPLE is assumed to be the example command, and it is prefixed with PS > 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] 0x2800 in lieu of space(s) after the >: this character will render like a space in terminals, but won't be trimmed by PowerShell.

  4. 237dmitry commented on May 18, 2024

    @237dmitry

    I can provide cut-down versions

    I tried simple function and it reproduces your issue. Workaround:

    ss

  5. daverayment commented on May 19, 2024

    @daverayment
    Author

    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>Something

    instead of:

    PS> Something

    The default behaviour, as detailed by Michael Klement (@mklement0), is problematic for a number of reasons:

    1. Auto-adding the PS > is inconsistent with the in-built cmdlet's examples, which are all presented un-prefixed.
    2. Auto-adding the PS > conflicts directly with all the examples on Microsoft's about Comment Based Help help page. All the examples in that guide have PS> present as prefixes to each of the example commands. Note the lack of space between the PS and >. This is the guide I followed when creating my own function's documentation.
    3. It means developers cannot provide comments before the command. I recognise from the guide and Michael Klement (@mklement0) 's advice that the intention is for comments and descriptions to be after the command example itself, so I'm happy to change my examples to fit this pattern, but it still feels a bit restrictive. This is especially galling because the in-built commands have additional info in the header for each example:
    ------- Example 3: Display more information for a cmdlet -------
    
        Get-Help Format-Table -Detailed
        Get-Help Format-Table -Full
    

    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.

    1. It makes multi-line examples more difficult to document, because the developer has to treat the first line differently.

    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-Help is 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 😀

  6. krzydoug commented on May 23, 2024

    @krzydoug

    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.

    I always wondered why there wasn't a way to add additional details after .EXAMPLE. That'd be nice

    Wishful thinking

    Function Test-Function {
        <#
        .EXAMPLE Some additional details
        Test-Function
        <#
    }
  7. theJasonHelmick commented on May 29, 2024

    @theJasonHelmick
    Collaborator

    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.

  8. added
    Up-for-GrabsUp-for-grabs issues are not high priorities, and may be opportunities for external contributors
    and removed
    Needs-TriageThe issue is new and needs to be triaged by a work group.
    on May 29, 2024
  9. mklement0 commented on Jun 19, 2024

    @mklement0
    Contributor

    As for the desire to be able to specify custom titles for each .EXAMPLE section, see:

  10. microsoft-github-policy-service commented on Dec 17, 2024

    @microsoft-github-policy-service
    Contributor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Resolution-No ActivityIssue has had no activity for 6 months or moreUp-for-GrabsUp-for-grabs issues are not high priorities, and may be opportunities for external contributorsWG-Interactive-HelpSystemhelp infrastructure and formatting of help

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions