Powershell does not render my script help correctly

Question

I have a Powershell script with rather a big help at the beginning of it to be displayed with the Get-Help command - https://gist.github.com/MarkKharitonov/91698caf8c695902eacde2b6c7825bf1

I have two problems with the way the help is rendered. Specifically with the .EXAMPLE section. Here is an abbreviated version of the help (see the hyperlink for the full version of the script and the help):

<#
.SYNOPSIS
    Runs a WinDBG command or a script file.

...

.NOTES
    The default is to scan for images using the .imgscan /l. One has to check first with the WinDBG GUI to see if this is necessary, because this is a time consuming operation.

.EXAMPLE
    Please, find below a PowerShell session transcript showing the script invoked with the -Command parameter:

    PS D:\tmp\cantestr52 - 06-09-2017> cat C:\Users\mkharitonov\runcdb.config.ps1
    $Sosex = "E:\Utils\sosex\64\sosex.dll"
    $CDB = "e:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe"
    $SymbolsCache = "E:\Symbols"
    PS D:\tmp\cantestr52 - 06-09-2017> cat .\runcdb.config.ps1
    $dump = "d:\tmp\cantestr52 - 06-09-2017\Quartz.Server.DMP"
    $ImagePath = "d:\tmp\cantestr52 - 06-09-2017\BJE"
    $NoScanForImages = $false
    PS D:\tmp\cantestr52 - 06-09-2017> runcdb.ps1 -Command "!dumpheap -mt 00007fff11d90f78 -live"
    ...        
    PS D:\tmp\cantestr52 - 06-09-2017>

    The script produced two log files:
    c:\Users\MKHARI~1\AppData\Local\Temp\!dumpheap_-mt_00007fff11d90f78_-live.log.init 
    c:\Users\MKHARI~1\AppData\Local\Temp\!dumpheap_-mt_00007fff11d90f78_-live.log

    Here is the WinDBG code executed by the script:
    | .logopen "c:\Users\MKHARI~1\AppData\Local\Temp\!dumpheap_-mt_00007fff11d90f78_-live.log.init"
    | .imgscan /l
    | .load E:\Utils\sosex\64\sosex.dll
    | !lhi
    | .logclose
    | .logopen "c:\Users\MKHARI~1\AppData\Local\Temp\!dumpheap_-mt_00007fff11d90f78_-live.log"
    | !dumpheap -mt 00007fff11d90f78 -live
    | .logclose
    | q
#>

Problem 1

Notice that the last lines start with |. This is because of .logopen - PowerShell attempts to treat it as a help section keyword, like .NOTES or .EXAMPLE. Of course, there is no such keyword and so PowerShell just truncates the help output and stops short of showing the last lines. I had to escape the dot somehow, but could not figure out the way.

Problem 2

Please, observe:

Notice the C:\PS> in the output. Of course, it is not part of my help.

So, two questions - how to escape the first dot in a help line and what is the source of the C:\PS> in the help output above?

My guess is that this is a "by design" thing. I would think this would be more of a .NOTES entry than a .EXAMPLE entry. The script header is extremely poorly documented, so I doubt you'll find much help on this. — Bacon Bits
– Bacon Bits, Commented Aug 9, 2017 at 21:35
Seems like it's a bug or redesign on Microsoft's side. Even following their docs I end up with your issue, contrary to their screenshot. It seems to insert the prompt on the first line of the example body, unless you have the > character — AP.
– AP., Commented Aug 9, 2017 at 21:44
As far as .logopen is concerned, I do not see your issue, at least on version 5.1.15063.502 — AP.
– AP., Commented Aug 9, 2017 at 21:46

briantist · Accepted Answer · 2017-08-09 21:56:45Z

5

Problem 1 - (lines beginning with dot `.`)

I don't think there's any getting around this with comment based help, but if you use XML based help then I don't think it would be an issue. That's a big change though.

Problem 2 - (prompt string)

It seems to do this with all examples, and isn't likely to be avoided with XML help. For what it's worth, I don't like this behavior either.

However, I will say that your example, I think, does not properly follow the format of what an example is. Your explanation that looks awkward in front of a prompt shouldn't be in the example section.

After .EXAMPLE you should just put the line of code (a short explanation could maybe go after the code).

More explanation can be given in .NOTES, or in linked documentation.

edited Aug 9, 2017 at 21:56

answered Aug 9, 2017 at 21:51

briantist

48.3k6 gold badges94 silver badges139 bronze badges

Sign up to request clarification or add additional context in comments.

Collectives™ on Stack Overflow

Powershell does not render my script help correctly

1 Answer 1

Problem 1 - (lines beginning with dot `.`)

Problem 2 - (prompt string)

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Problem 1 - (lines beginning with dot .)

Problem 2 - (prompt string)

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related

Problem 1 - (lines beginning with dot `.`)