CODEWITHSUNDEEP
powershell
mark
mark

Reputation: 62886

Powershell does not render my script help correctly

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: enter image description here

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?

Upvotes: 2

Views: 148

Answers (1)

briantist
briantist

Reputation: 47872

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.

Upvotes: 5

Related Questions