No newline after an example's introduction

[sargola]

heya,
lovely work you have done!
but after an example's introduction a newline is missing (so the introduction-text and the code are in one line)
thx and keep up the good work
Michi

[ChrisLambrou]

Hi! Thanks for this. I'm looking into this. It's turning out to be a bit of a pain to get whitespace to work well both when formatted by the PowerShell Get-Help cmdlet and in the help pane of the ISE Steroids tool that's very common amongst PowerShell users. I'm aiming to get a fix by the end of today, fingers crossed.

[ChrisLambrou]

I've been playing around with this all evening, and have come to the conclusion that the problem is actually a bug in the Get-Help cmdlet. Consider the following example XML:

<command:example>
  <maml:title>----------  EXAMPLE 1  ----------</maml:title>
  <maml:introduction>
    <maml:para>Introduction paragraph1.</maml:para>
    <maml:para>Introduction paragraph2.</maml:para>
  </maml:introduction>
  <dev:code>Write-Host 'Hello World'</dev:code>
  <dev:remarks>
    <maml:para>Remarks paragraph 1.</maml:para>
    <maml:para>Remarks paragraph 2.</maml:para>
  </dev:remarks>
</command:example>

When rendered by the Get-Help cmdlet, it ought to look something like this:

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

Introduction paragraph1.

Introduction paragraph2.


Write-Host 'Hello World'


Remarks paragraph 1.

Remarks paragraph 2.


----------  EXAMPLE 2  ----------

Unfortunately, it actually looks like this:

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

Introduction paragraph1.
Introduction paragraph2.Write-Host 'Hello World'


Remarks paragraph 1.

Remarks paragraph 2.
----------  EXAMPLE 2  ----------

I've lost count of the different ways I've modified the example XML above to trick the Get-Help cmdlet into producing acceptably presented output. Nothing worked. Interestingly, in all of the Microsoft-produced help XML that I looked through, I could only find two distinct cases of an example introduction being specified.

The first case appears to be an attempt to insert a blank line between the title of the example and its body, like this:

<maml:introduction>
  <maml:para>
  </maml:para>
</maml:introduction> 

The second case simply adds the C:\PS> prompt in front of the actual example cmldet invocation. This actually relies on the apparently buggy behaviour!

<maml:introduction>
  <maml:para>C:\PS&gt;</maml:para>
</maml:introduction> 

My conclusion at this point is that this feature of specifying an introduction to an example is either broken or intentionally a bit rubbish. I think avoiding it is probably the best advice right now, unfortunately.

[sargola]

heya!

thanks for the big effort! i actually tried to get the desired output as well and failed.

it really looks like its a get-help problem. and i also falled back to write my code comments after the code example.

thanks again,
michi

[johncrim]

In light of this issue, I'm going with:

	/// <example>
	/// <code>
	/// <para>
	///  Introduction paragraph...
	/// </para>
	///  Powershell code example
	/// </code>
	/// </example>

... which provides the desired blank line between the intro paragraph and the code. Eg:

    ----------  EXAMPLE 1  ----------
    
    Introduction paragraph...
	    
    Powershell code example

That's certainly far better than combining the 2 lines into one.

It's unlikely to render well in Sandcastle, but the primary use of my XML comments in C# cmdlets is for Powershell help.

I'd love to hear if others see major flaws in this approach.

[ChrisLambrou]

I'd like to see the MAML that's generated for this. If there's a way to generate MAML that actually renders well in the Get-Help cmdlet, and reasonably well in other common renderings (e.g. VS doc popup, R# quick doc, ISE Steroids), then I'll update this tool accordingly. I'm a bit pressed for time right now, but will hopefully get a chance to look at this at the weekend.

[johncrim]

For this example:

	/// <example>
	/// <code>
	/// <para>
	///  Introduction paragraph...
	/// </para>
	///  $wd = Get-Location
	/// </code>
	/// </example>

The MAML is:

    <command:examples>
      <command:example>
        <maml:title>----------  EXAMPLE 1  ----------</maml:title>
        <dev:code>Introduction paragraph...

$wd = Get-Location</dev:code>
      </command:example>
    </command:examples>

I wasn't able to get the example to show in the VS doc popup. I see the summary/description in the VS doc popup, but no example, even when I remove the intro.

The R# quick doc is ok IMO:

[Omzig]

Something Else happens when it converts multi line < Code > to maml.

    ///   <code>PS C:\>$timeSpan = New-TimeSpan -Hours 1 -Minutes 1 -Seconds 1
    /// PS C:\>$password = ConvertTo-SecureString -String "bob" -Force -AsPlainText</code>

turns into:

        <dev:code>PS C:\&gt;$timeSpan = New-TimeSpan -Hours 1 -Minutes 1 -Seconds 1
            PS C:\&gt;$password = ConvertTo-SecureString -String "bob" -Force -AsPlainText</dev:code>
        <dev:remarks>

and should be:

        <dev:code>PS C:\&gt;$timeSpan = New-TimeSpan -Hours 1 -Minutes 1 -Seconds 1
PS C:\&gt;$password = ConvertTo-SecureString -String "bob" -Force -AsPlainText</dev:code>
        <dev:remarks>

it puts spaces in there, that shows up in the help, if you manually remove the spaces, then it looks good in the powershell doc.

[ChrisLambrou]

Yeah, this also relates to the tricky problem of trying to extract the original intent from the XML in the XML Doc comment file. I've tried this a few different ways over the last few months, but haven't found anything that works very well. Sigh...

[Omzig]

So I have been looking inside the doc.xml gen, any line that does not begin with an xml tag, is basically indented because of the xml tools that format the file. I would say that since this xml doesn't normally know about white space, that the white space in front of your helpfile.xml can be safely removed if you go line by line and just remove beginning white space. You cannot control beginning white space to indent anyways.

pseudocode:
foeach line if does not begin with <, then remove each " " till the first char in the line is not " ".

[ChrisLambrou]

Yeah, I tried something as simple as that, but ran into lots of awkward edge cases, as the problem turns out not to be quite as easy as it may first appear. I wrote up a few notes on this. I'll dig them out and have another go at this over the Christmas break. It would be nice to get this fixed.