diff --git a/src/MamlWriter/MamlConstants.cs b/src/MamlWriter/MamlConstants.cs index 824282cb..edc454f4 100644 --- a/src/MamlWriter/MamlConstants.cs +++ b/src/MamlWriter/MamlConstants.cs @@ -39,5 +39,15 @@ internal static partial class Constants internal const string MamlLinkTextTag = "maml:linkText"; internal const string MamlUriTag = "maml:uri"; internal const string MamlFileExtensionSuffix = "-help.xml"; + // Legacy compatibility: + // Older versions of platyPS (prior to 1.0.2) emitted `` + // in Export-MamlCommandHelp, and some existing MAML help files still + // use ``. PowerShell’s built-in MAML reader accepts both + // because it matches only the local-name `uri`. + // + // Import-MamlHelp must continue to support `` for + // compatibility with legacy MAML content. This constant can be removed + // once all supported MAML formats use `` exclusively. + internal const string MamlCommandUriTag = "command:uri"; } } diff --git a/src/Transform/TransformMaml.cs b/src/Transform/TransformMaml.cs index 8c335888..e7a9fe2f 100644 --- a/src/Transform/TransformMaml.cs +++ b/src/Transform/TransformMaml.cs @@ -137,26 +137,34 @@ private Collection ReadRelatedLinks(XmlReader reader) { do { + var subTree = reader.ReadSubtree(); + string? linkText = null; string? uri = null; - if (reader.ReadToFollowing(Constants.MamlLinkTextTag)) + while (subTree.Read()) { - linkText = reader.ReadElementContentAsString(); - } - - if (reader.ReadToFollowing(Constants.MamlUriTag)) - { - uri = reader.ReadElementContentAsString(); + switch (subTree.Name) + { + case Constants.MamlLinkTextTag: + linkText = reader.ReadElementContentAsString(); + continue; + case Constants.MamlUriTag: + case Constants.MamlCommandUriTag: + // Support `` for legacy MAML compatibility. + // PowerShell’s built-in MAML reader accepts both `` and + // `` (matching only the local-name `uri`), so platyPS + // must do the same. This branch can be removed once legacy MAML + // formats are no longer supported. + uri = reader.ReadElementContentAsString(); + continue; + } } if (linkText != null && uri != null) { relatedLinks.Add(new Links(uri, linkText)); } - - reader.ReadEndElement(); - } while (reader.ReadToNextSibling(Constants.MamlNavigationLinkTag)); } } diff --git a/test/Pester/ImportMamlHelp.Tests.ps1 b/test/Pester/ImportMamlHelp.Tests.ps1 index 1d07584e..4611a49a 100644 --- a/test/Pester/ImportMamlHelp.Tests.ps1 +++ b/test/Pester/ImportMamlHelp.Tests.ps1 @@ -1,7 +1,7 @@ # Copyright (c) Microsoft Corporation. # Licensed under the MIT License. -Describe "Import-YamlHelp tests" { +Describe "Import-MamlHelp tests" { Context "Basic tests" { BeforeAll { $mamlFile = "${PSScriptRoot}/assets/Microsoft.PowerShell.Commands.Utility.dll-Help.xml" @@ -97,5 +97,13 @@ Describe "Import-YamlHelp tests" { $values | Should -BeExactly $expectedValues } } + + Context 'Load legacy' { + It 'load in related links' { + $mamlFile = "${PSScriptRoot}/assets/legacy-maml/command:uri-in-related-links.xml" + $importedCmd = Import-MamlHelp $mamlFile + $importedCmd.RelatedLinks[0].Uri | Should -Be "https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/get-date?view=powershell-7.4&WT.mc_id=ps-gethelp" + } + } } } diff --git a/test/Pester/assets/legacy-maml/command:uri-in-related-links.xml b/test/Pester/assets/legacy-maml/command:uri-in-related-links.xml new file mode 100644 index 00000000..48861dd4 --- /dev/null +++ b/test/Pester/assets/legacy-maml/command:uri-in-related-links.xml @@ -0,0 +1,36 @@ + + + + + Get-Date + + Gets the current date and time. + + Get + Date + + + + + + + Get-Date + + + + + + + + + + + + + + Online Version + https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/get-date?view=powershell-7.4&WT.mc_id=ps-gethelp + + + +