Merge-MarkdownHelp does weird stuff when parameter description contains \#Inbox\#

chrisda commented 3 years ago

A parameter description in a markdown topic contains \#Inbox\#. Apparently, this generates an error in Merge-MarkdownHelp and causes it to not merge the next cmdlet topic correctly.

Difficult to explain; see the attached files and explanation.

Steps to reproduce

Create the following folder structure with the appropriate files:
\Exchange Online\New-MailboxFolder.md \Exchange Online\New-MailboxImportRequest.md \Exchange Online\New-MailboxRestoreRequest.md \Exchange Server 2010\New-MailboxFolder.md \Exchange Server 2010\New-MailboxImportRequest.md \Exchange Server 2010\New-MailboxRepairRequest.md \Exchange Server 2010\New-MailboxRestoreRequest.md \Exchange Server 2013\New-MailboxFolder.md \Exchange Server 2013\New-MailboxImportRequest.md \Exchange Server 2013\New-MailboxRepairRequest.md \Exchange Server 2013\New-MailboxRestoreRequest.md \Exchange Server 2016\New-MailboxFolder.md \Exchange Server 2016\New-MailboxImportRequest.md \Exchange Server 2016\New-MailboxRepairRequest.md \Exchange Server 2016\New-MailboxRestoreRequest.md \Exchange Server 2019\New-MailboxFolder.md \Exchange Server 2019\New-MailboxImportRequest.md \Exchange Server 2019\New-MailboxRepairRequest.md \Exchange Server 2019\New-MailboxRestoreRequest.md Note that New-MailboxImportRequest and New-MailboxRestoreRequest contain the following line of text in the ExcludeFolders parameter description: ```text `##/*`: Use this syntax to denote a well-known folder regardless of the folder's name in another language. For example, \#Inbox\# denotes the Inbox folder even if the Inbox is localized in Turkish, which is Gelen Kutusu. Well-known folders include the following types: ```

Run the following commands:


$x = "<path>\Exchange Server 2010","<path>\Exchange Server 2013","<path>\Exchange Server 2016","<path>\Exchange Server 2019","<path>\Exchange Online"
Merge-MarkdownHelp -Path $x -OutputPath "<path>\platyPSissue\Merged" -ExplicitApplicableIfAll

Expected behavior

Cmdlet topics are merged correctly.

Actual behavior

Errors:

PS C:\Users\jdoe> Merge-MarkdownHelp -Path $x -OutputPath "<path>\Merged" -ExplicitApplbleIfAll

    Directory: <path>\Merged

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----          3/1/2021   5:57 PM          11293 New-MailboxFolder.md
Exception calling "NodeModelToMamlModel" with "1" argument(s): "<path>\Exchange
Online\New-MailboxImportRequest.md:350:(857) 'For example, #Inbox# denotes the Inbox folder even...'
 Expect Heading"
At C:\Users\jdoe\Documents\WindowsPowerShell\Modules\platyPS\0.14.1\platyPS.psm1:1574 char:9
+         $maml = $t.NodeModelToMamlModel($model)
+         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
    + FullyQualifiedErrorId : HelpSchemaException

Exception calling "Merge" with "1" argument(s): "Object reference not set to an instance of an object."
At C:\Users\jdoe\Documents\WindowsPowerShell\Modules\platyPS\0.14.1\platyPS.psm1:574 char:13
+             $newModel = $merger.Merge($dict)
+             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
    + FullyQualifiedErrorId : NullReferenceException

-a----          3/1/2021   5:57 PM          11293 New-MailboxImportRequest.md
-a----          3/1/2021   5:57 PM          12636 New-MailboxRepairRequest.md
Exception calling "NodeModelToMamlModel" with "1" argument(s): "<path>\Exchange
Online\New-MailboxRestoreRequest.md:430:(1076) 'For example, #Inbox# denotes the Inbox folder even...'
 Expect Heading"
At C:\Users\jdoe\Documents\WindowsPowerShell\Modules\platyPS\0.14.1\platyPS.psm1:1574 char:9
+         $maml = $t.NodeModelToMamlModel($model)
+         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
    + FullyQualifiedErrorId : HelpSchemaException

Exception calling "Merge" with "1" argument(s): "Object reference not set to an instance of an object."
At C:\Users\jdoe\Documents\WindowsPowerShell\Modules\platyPS\0.14.1\platyPS.psm1:574 char:13
+             $newModel = $merger.Merge($dict)
+             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
    + FullyQualifiedErrorId : NullReferenceException

-a----          3/1/2021   5:57 PM          12653 New-MailboxRestoreRequest.md

The merged New-MailboxImportRequest.md topic has the same content as the merged New-MailboxFolder.md topic.
The merged New-MailboxRestoreRequest.md topic has the same content as the merged New-MailboxRepairReuest.md topic.

Files/folders are attached.

platyPSissue.zip

Environment data

platyPS 0.14.1
Windows 10 Enterprise 20H2
Windows PowerShell 5.1

sdwheeler commented 3 years ago

I looks like you are inconsistent with the escape characters. Some cases you have #Inbox#, and other cases you have \#Inbox\#.

I recommend that those values be put in code ticks `#Inbox#`. That will be the safest and matches the PowerShell-Doc style guide the best.

@chrisda Can you try using backticks and test again?

chrisda commented 3 years ago

Thanks. I worked it out with a combination of code tick escapes for some instances and regular back slash escapes for others.

Closing

PowerShell / platyPS