Powershell无法正确呈现我的脚本帮助

Question

我有一个Powershell脚本，在它的开头有一个很大的帮助，用Get-Help命令显示 - https://gist.github.com/MarkKharitonov/91698caf8c695902eacde2b6c7825bf1

我在呈现帮助的方式上遇到两个问题。特别是.EXAMPLE部分。以下是帮助的缩写版本（请参阅脚本完整版的超链接和帮助）：

<#
.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
#>

问题1

请注意，最后一行以 | 开头。这是因为.logopen - PowerShell会尝试将其视为帮助部分关键字，例如.NOTES或.EXAMPLE。当然，没有这样的关键字，所以PowerShell只是截断了帮助输出，并且没有显示最后一行。我不得不以某种方式逃离这个点，但无法弄明白。

问题2

请观察：

请注意输出中的 C：\ PS＆gt; 。当然，这不是我帮助的一部分。

那么，有两个问题 - 如何逃避帮助热线中的第一个点以及上面帮助输出中 C：\ PS＆gt; 的来源是什么？

Answer 1

问题1 - （以点.开头的行）

我认为通过基于评论的帮助可以解决这个问题，但是如果你使用XML based help那么我认为不会是一个问题。但这是一个很大的变化。

问题2 - （提示字符串）

似乎所有示例都是这样做的，并且在XML帮助下不可能避免这种情况。对于它的价值，我也不喜欢这种行为。

但是，我想我会说你的例子并没有正确地遵循一个例子的格式。您在提示前看起来很尴尬的解释不应该在示例部分中。

在.EXAMPLE之后你应该放一行代码（一个简短的解释可能会在代码之后）。

可以在.NOTES或链接文档中提供更多说明。