From 575cf3a00c619d2e4a8d15e4ccf7835a1b730459 Mon Sep 17 00:00:00 2001 From: teramako Date: Fri, 10 Jul 2026 22:49:18 +0900 Subject: [PATCH 1/2] Add a test for loading MamlHelp which contains legacy `` --- test/Pester/ImportMamlHelp.Tests.ps1 | 10 +++++- .../command:uri-in-related-links.xml | 36 +++++++++++++++++++ 2 files changed, 45 insertions(+), 1 deletion(-) create mode 100644 test/Pester/assets/legacy-maml/command:uri-in-related-links.xml 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 + + + + From cd22ab0bbe10299e90e5e70ed9dd8b7ec292cc8c Mon Sep 17 00:00:00 2001 From: teramako Date: Fri, 10 Jul 2026 22:56:04 +0900 Subject: [PATCH 2/2] Fix: read `` or `` in TransformMaml.ReadRelatedLinks Legacy MAML help may be written using ``. PowerShell's built-in MAML reader (Get-Help / Show-HelpPreview) correctly reads `` because it matches only the local-name `uri` and does not require the `maml:` namespace. platyPS should maintain compatibility with this behavior. Older versions of platyPS (prior to 1.0.2) emitted `` in Export-MamlCommandHelp, so Import-MamlHelp must support this legacy format to ensure round-trip compatibility. The XmlException occurs because TransformMaml.ReadRelatedLinks calls ReadEndElement() even when the reader is not positioned at an end element. This happens whenever `` is missing, regardless of PR #849. This is a long-standing reader-side bug. --- src/MamlWriter/MamlConstants.cs | 10 ++++++++++ src/Transform/TransformMaml.cs | 28 ++++++++++++++++++---------- 2 files changed, 28 insertions(+), 10 deletions(-) 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)); } }