Plain text lists not migrated into markdown as lists.

[TimShererAtAquent]

Plaintext formatting for lists in the maml files is not migrated to MD files in a useful way. The way that we do PowerShell lists is as follows:

Introductory text:[linebreak][linebreak]
[hyphen][hyphen][space]list item[linebreak]
[hyphen][hyphen][space]list item[linebreak]
[hyphen][hyphen][space]list item[linebreak][linebreak]

These appear in the MarkDown as follows: (Example from Get-Help.md)

**The full view of help (-Full) includes a table of information about the parameters.
The table includes the following fields:

-- Required: Indicates whether the parameter is required (true) or optional (false).
-- Position: Indicates whether the parameter is named or positional (numbered). Positional parameters must appear in a specified place in the command.
-- "Named" indicates that the parameter name is required, but that the parameter can appear anywhere in the command.
-- indicates that the parameter name is optional, but when the name is omitted, the parameter must be in the place specified by the number. For example, "2" indicates that when the parameter name is omitted, the parameter must be the second (2) or only unnamed parameter in the command. When the parameter name is used, the parameter can appear anywhere in the command.
-- Default value: The parameter value that Windows PowerShell uses if you do not include the parameter in the command.**

Results in my atom editor preview window:
The full view of help (-Full) includes a table of information about the parameters. The table includes the following fields:
-- Required: Indicates whether the parameter is required (true) or optional (false). -- Position: Indicates whether the parameter is named or positional (numbered). Positional parameters must appear in a specified place in the command. -- "Named" indicates that the parameter name is required, but that the parameter can appear anywhere in the command. -- \ indicates that the parameter name is optional, but when the name is omitted, the parameter must be in the place specified by the number. For example, "2" indicates that when the parameter name is omitted, the parameter must be the second (2) or only unnamed parameter in the command. When the parameter name is used, the parameter can appear anywhere in the command. -- Default value: The parameter value that Windows PowerShell uses if you do not include the parameter in the command.

We need to round-trip these, preferably turning out plaintext format into a simple markdown unordered list. For genuine round tripping, the simple markdown unordered list should be translated into the current list format in the maml file.

[vors]

I agree that we should produce a valid markdown for lists, from existing MAML list patterns.
That means, we should transform -- lists into - or * lists.

However, I would argue that we should not try to do the round-trip: convert markdown lists into MAML lists (essentially it's a plain-text, so - should do just fine as a list item mark).
Such growing logic in the MAML transformation would add complexity and make transformations less straightforward.

[TimShererAtAquent]

We should see how it renders in the plaintext output in a PS console window.

I don't know the original reason that PS adopted this convention. Maybe the PowerShell team can shed some light.

[vors]

Implemented via a3ce3ed

New-MarkdownHelp -ConvertDoubleDashLists

Example:

https://gist.github.com/vors/803557096ae25a049139f24ff555f4bb