Error generating About: StartIndex cannot be less than zero

[rrg92]

Prerequisites

• Write a descriptive title.
• Make sure you are able to repro it on the latest released version
• Search the existing issues.

Steps to reproduce

1. Create a markdown file, (e.g., 'C:\temp\PlatyTemp\about_PlatyProblem.md') with that content:

# Platy Problem
## about_PlatyProblem

# SHORT DESCRIPTION 

Demonstrates a problem with PlatyPS when a long word is present.

# LONG DESCRIPTION 

プロバイダーもコマンドをエクスポートします。これらのコマンド名は、一般的にプロバイダー名で始まる場合が多いです。エクスポートされたコマンドのパターンについては、プロバイダーのドキュメントを参照してください。

2. Run New-ExternalHelp -Path C:\temp\PlatyTemp -OutputPath C:\temp\PlatyTemp -Force

Expected behavior

Under normal circumstances, PlatyPS should wrap text lines based on the `MaxAboutWidth` setting (default 80), ensuring that once a line exceeds the maximum X characters, the remaining text is moved to the next line.

Actual behavior

An exception occurs with the following message:  
`StartIndex cannot be less than zero`

Error details

at System.String.Substring(Int32 startIndex, Int32 length)
   at Markdown.MAML.Renderer.TextRenderer.WrapAndAppendLines(String text, StringBuilder sb)
   at Markdown.MAML.Renderer.TextRenderer.AddAboutParagraph(ParagraphNode paragraphNode)
   at Markdown.MAML.Renderer.TextRenderer.AboutMarkdownToString(DocumentNode document)

Environment data

ModuleType Version    Name                                ExportedCommands
---------- -------    ----                                ----------------
Script     0.14.2     platyPS                             {New-MarkdownHelp, Get-MarkdownMetadata, New-ExternalHelp, New-YamlHelp...}



Name                           Value
----                           -----
PSVersion                      5.1.19041.4894
PSEdition                      Desktop
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}
BuildVersion                   10.0.19041.4894
CLRVersion                     4.0.30319.42000
WSManStackVersion              3.0
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1

Visuals

No response

[rrg92]

There is a previous issue that was closed with an external resolution: #251.
However, I believe that PlatyPS should handle this situation better.

Workaround for who is getting same problem: Increase -MaxAboutWidth, set it to maximum line length for lines with text without space

I performed some initial troubleshooting by looking at the source code.

As indicated by the exception stack trace, the problem occurs in the function WrapAndAppendLines.
This function splits the input string (which originates from a markdown paragraph) by spaces, assuming that spaces separate words.

platyPS/src/Markdown.MAML/Renderer/TextRenderer.cs

Lines 130 to 133 in f9fa128

	const string singleSpace = " ";
	var words = text.Split(' ');
	text = "";

While the current line does not exceed MaxAboutWidth characters, it continues to add these split words.
The content is buffered in a variable called text.

platyPS/src/Markdown.MAML/Renderer/TextRenderer.cs

Lines 135 to 138 in f9fa128

	foreach (var word in words)
	{
	if (word.Contains("\r\n"))
	{

In each loop iteration over words, it checks if text + word exceeds MaxAboutWidth. If so, it starts a new line.
This check involves using the Substring function, retrieving the length of the text variable minus 1.

In the case at hand, the Japanese text does not contain spaces. So, during the first iteration of the word loop, it enters the second else if condition.
Since text is still empty (on the first loop), the length returns 0, resulting in a start index exception.

platyPS/src/Markdown.MAML/Renderer/TextRenderer.cs

Lines 155 to 163 in f9fa128

	else if (text.Length + word.Length > (_maxLineWidth - 4))
	{
	if (StringComparer.OrdinalIgnoreCase.Equals(text.Substring(text.Length - 1), singleSpace))
	{
	text = text.Substring(0, text.Length - 1);
	}
	sb.AppendFormat("{0}{1}{2}", AboutIndentation, text, NewLine);
	text = word + singleSpace;

I believe a simple solution would be to handle cases where a word with no spaces exceeds the maximum width. In such cases, it should fill the line with up to MaxAboutWidth characters and start a new line accordingly.

[sdwheeler]

Thank you for your contribution. We are no longer maintaining the v0.14 version of platyPS. If you’re interested in continuing to help, we’d love your support on the release version of Microsoft.PowerShell.PlatyPS v1.0.0.