Multiline examples don't display as markdown code

[Kreloc]

Steps to reproduce

Have a function with multiple lines in an .EXAMPLE section

.EXAMPLE
     $verbs = Get-Verb
     $verbs

Expected behavior

------------------------- EXAMPLE 1 -------------------------

     $verbs = Get-Verb
     $verbs

Actual behavior

------------------------- EXAMPLE 1 -------------------------

     $verbs = Get-Verb

$verbs

v0.5.0

[vors]

@Kreloc ah, interesting. Thank you for reporting it!
It's yet another help-engine problem that we probably should work-around in platyPS.

[jdhitsolutions]

I might as well add something to the mix here. I often have multiple commands in an example:

PS C:\> $a = Get-Service
PS C>> $a | group Status

Followed by a blank line and then an explanation. I'd love for the PowerShell commands to be treated as a code block.

[vors]

@jdhitsolutions sorry for the super late reply, slipped out of my attention :(

If you still care, this is a duplicate requirement of #294 you can read the long conversation there for more details.
TLDR: all example code snippets should get powershell moniker.

[BernieWhite]

So this is an issue because the PowerShell help system considers the second line a remark instead of code regardless of if it's prefixed with PS C:\>.

[midacts]

It seems like this issue probably isn't being looked at anymore or isn't going to be resolved, right?
Does anyone have a work around?

I guess just making everything be on one line

[BernieWhite]

@midacts anything not closed will be looked at but more common issues are prioritised.

[BernieWhite]

This particular issue as i understand it only applies one inital help import into markdown. So a copy/paste from help to markdown would also allow you to work around the issue.

[Greg-Smulko]

I created a big of regex magic to fix this issue, it can help somebody hopefully.

    New-MarkdownHelp -Module MyModuleToDocument -OutputFolder $OutputDir -Force

    $OutputDir | Get-ChildItem -File | ForEach-Object {
        # fix formatting in multiline examples
        $content = Get-Content $_.FullName -Raw
        $newContent = $content -replace '(## EXAMPLE [^`]*)(```\r\n)([^`]*)(```\r\n)(\r\n)([^#]*)(\r\n\r\n)+([^#]+)(#)', '$1$2$3$6$5$4$7$8$9'
        if ($newContent -ne $content) {
            Set-Content -Path $_.FullName -Value $newContent -Force
        }
    }

[vors]

Would you care to try to include such heuristic in platypus when we generate the examples code from Get-Help object?

[Greg-Smulko]

@vors, TL;DR: I gave it a try and realized that there is no way to come up with the heuristics that works for all scenarios.

Unfortunately, it seems that there is no way to distinguish between these two scenarios:

.EXAMPLE
PS C:\> Test-PlatyPSFunction "Multiline example, code only"
Generated output (no new line between these two lines)

and

.EXAMPLE
Test-PlatyPSFunction "Single line of code"

Single line of description - a new line that separates the code section doesn't matter :(

As it was said before, the problem is that Get-Help treats only the first line as code, and all the rest as remarks. What's even worse, it also trims all the new lines, so the author's intent is lost.

I came up with a couple of regexes:

1. a greedy one, always treats the first paragraph from the remarks as code

'(## EXAMPLE [^`]+?```\r\n[^`\r\n]+?\r\n)(```\r\n\r\n)([^#]+?\r\n)(\r\n)', '$1$3$2$4'

2. not as greedy as the previous one; always treats the last paragraph as a remark. It still doesn't work correctly for a single line of code and two paragraphs of remarks. It also doesn't work if there are no remarks at all.

'(## EXAMPLE [^`]+?```\r\n[^`\r\n]+?\r\n)(```\r\n\r\n)([^#]+?\r\n)(\r\n)([^#]+)(#)', '$1$3$2$4$5$6'

Feel free to test the above e.g. on http://regexstorm.net/tester using the below test data:

test data

Generated markdown:

	"---
	external help file:
	Module Name:
	online version:
	schema: 2.0.0
	---

	# Test-PlatyPSFunction

	## SYNOPSIS
	Copies an item from one location to another.

	## SYNTAX

	```
	Test-PlatyPSFunction [-Confirm]
	```

	## DESCRIPTION
	The Copy-Item cmdlet copies an item (...)

	## EXAMPLES

	### EXAMPLE 1
	```
	Test-PlatyPSFunction "Just a single line example, without remarks"
	```

	### EXAMPLE 2
	```
	Test-PlatyPSFunction "Multiline example, code only"
	```

	PS C:\\\> Generated output (no new line between these two lines, but it doesn't really matter)

	### EXAMPLE 3
	```
	Test-PlatyPSFunction "Single line of code"
	```

	Single paragraph of remarks - a new line that separates the code section doesn't matter :(

	### EXAMPLE 4
	```
	Test-PlatyPSFunction "Single line of code"
	```

	First paragraph of remarks - a new line that separates the code section doesn't matter :(

	Second paragraph of remarks - the first paragraph will be treated as code :(

	### EXAMPLE 5
	```
	$Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul"
	```

	Copy-Item "C:\MyRemoteData\test.log" -Destination "D:\MyLocalData\" -FromSession $Session
	My output

	The first command creates a session to the remote computer named Server01 with the credential of Contoso\PattiFul and stores the results in the variable named $Session.

	The second command uses the Copy-Item cmdlet to copy test.log from the remote C:\MyRemoteData\ to the local D:\MyLocalData folder using the session information stored in the $Session variable.
	This command does not delete the original file.

	## PARAMETERS

	### -Confirm
	Prompts you for confirmation before running the cmdlet.

	```yaml
	Type: SwitchParameter
	Parameter Sets: (All)
	Aliases:

	Required: False
	Position: Named
	Default value: False
	Accept pipeline input: False
	Accept wildcard characters: False
	```

	## INPUTS

	### System.String. You can pipe a string that contains a path to this cmdlet.
	## OUTPUTS

	### None or an object representing the copied item.
	## NOTES

	## RELATED LINKS

	[Online Version: http://go.microsoft.com/fwlink/?LinkId=821574]()

	"

Original comment-based help template based on https://technet.microsoft.com/en-us/library/hh847834.aspx :

.OUTPUTS
None or an object representing the copied item.

.EXAMPLE
PS C:\> Test-PlatyPSFunction "Just a single line example, without remarks"

.EXAMPLE
PS C:\> Test-PlatyPSFunction "Multiline example, code only"
PS C:\> Generated output (no new line between these two lines, but it doesn't really matter)

.EXAMPLE
PS C:\> Test-PlatyPSFunction "Single line of code"

Single paragraph of remarks - a new line that separates the code section doesn't matter :(
    
.EXAMPLE
PS C:\> Test-PlatyPSFunction "Single line of code"

First paragraph of remarks - a new line that separates the code section doesn't matter :(

Second paragraph of remarks - the first paragraph will be treated as code :(

.EXAMPLE
$Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul"
Copy-Item "C:\MyRemoteData\test.log" -Destination "D:\MyLocalData\" -FromSession $Session
My output

The first command creates a session to the remote computer named Server01 with the credential of Contoso\PattiFul and stores the results in the variable named $Session.

The second command uses the Copy-Item cmdlet to copy test.log from the remote C:\MyRemoteData\ to the local D:\MyLocalData folder using the session information stored in the $Session variable. This command does not delete the original file.

.LINK
Online Version: http://go.microsoft.com/fwlink/?LinkId=821574

I can open a PR for the above, but I'm a bit worried about introducing a breaking change here.
Also, it doesn't support every scenario properly, so I'm pretty sure that it may break things for some people.

Another option is to add this as an optional feature, but then probably just letting people use the above regexes (or different ones) is easier, safer and more reasonable.

The heuristics can be improved by checking if the first paragraph of remarks looks more like code or more like text, but it feels like creating a lot of complexity just to create a workaround for a bug.

I assume that there is no way to have the Get-Help itself fixed?