Allow for blocks in <Example> or <Description> tags to not always include a blank line

[inspectorK]

There is no way to add newline characters to examples or description tags. It would be helpful to be able to add newline characters to allow for generation of tables of possible output or example output. The only way to do this is to include a tag for each line, but this adds a blank line in between each line, causing readability to suffer.

I would like the PowerShell help file to include a table of possible output of a cmdlet. Something like:

This is the desired output formatting.

The associated MAML would be:
maml:paraPointID Timestamp Value
1 "1-Apr-2015 11:00:00" 100
2 "2-Apr-2015 12:00:00" 100
3 "3-Apr-2015 13:00:00" 100</maml:para>

However, this cannot be done with xmldoc2cmdletdoc, as it will generate:
maml:paraPointID Timestamp Value</maml:para>
maml:para1 "1-Apr-2015 11:00:00" 100</maml:para>
maml:para2 "2-Apr-2015 12:00:00" 100</maml:para>
maml:para3 "3-Apr-2015 13:00:00" 100</maml:para>

This causes the output to have unnecessary blank lines in between each line. Unfortunately I don't have a screenshot of the exact output for the case above, but it looks similar to:

I imagine quite a few other users would benefit from being able to properly format example output or tables within examples or parameter descriptions.

Let me know if I can provide any additional information

[inspectorK]

Unfortunately the github editor doesn't seem to like the MAML either, the opening "<" makes github think its a quote, and the code ticks `` make is display awkwardly as well. I guess just note that the maml:para tags are enclosed in "<" and ">" properly.

[ChrisLambrou]

Hi!

You can format a block of XML by surrounding it like this:

```xml
<MyXmlElement>
Stuff here!
</MyXmlElement>
```

Which will then be displayed like this:

<MyXmlElement>
Stuff here!
</MyXmlElement>

I'm assuming you intended to write this:

<maml:para>PointID Timestamp Value
1 "1-Apr-2015 11:00:00" 100
2 "2-Apr-2015 12:00:00" 100
3 "3-Apr-2015 13:00:00" 100</maml:para>

[ChrisLambrou]

Okay, the problem here is that XmlDoc2CmdletDoc can't currently distinguish between deliberate newlines (as in your case) and incidental newlines, as in the following:

<summary>
<para type="description">
Although this comment appears as multiple lines in the C# source code, it's
really just a single paragraph. The newlines are present merely because it's
customary for source code to be limited horizontally to 80 characters (for
example - this varies from codebase to codebase).
</para>
</summary>

Since the practise of inserting newlines purely to keep the line length limited is so commonplace, the tool ignores the newline characters. I found that to do otherwise lead to lots of unwanted line breaks in the resulting MAML.

I guess what would really help here would be some support for more strict interpretation of the contents of a <para>...</para> element. Maybe I could support this with special handling of CDATA elements within <para> elements? For example, something like the following XML Doc might achieve what you're after:

<summary>
<para type="description">
This text, that comes before the following table, is
split onto multiple lines in the XML Doc, but appears
as a single line in the MAML: <![CDATA[

Heading1  Heading2
apple     123
ball      456
cat       789

]]>This text comes after the table, and is also split
onto multiple lines in the XML Doc, but appears as a single line in the MAML.
</para>
</summary>

which would appear in the MAML as:

<maml:para>This text, that comes before the following table, is split onto multiple lines in the XML Doc, but appears as a single line in the MAML:

Heading1  Heading2
apple     123
ball      456
cat       789

This text comes after the table, and is also split onto multiple lines in the XML Doc, but appears as a single line in the MAML.</maml:para>

I realise this is a bit clunky, though. 😞

[inspectorK]

Hi Chris,
Thanks for the thorough investigation, I understand the ignoring of newline characters to prevent a bunch of excess/unnecessary newlines in the MAML, and agree this should be the default behavior. Like you mention here though, some way to override this and build table or force a newline for formatting purposes would be extremely helpful.

While I agree it may not be the most graceful, I'm not sure how else you could distinguish the deliberate newlines within the <para>...</para> tags. (I am no expert in XML documentation commenting or the specifics of MAML) Considering that usually an example output may only be used for the first example in the cmdlet help, it would be very workable and just having a way to force the formatting would be extremely helpful and clean up a lot of cmdlet examples in the help :)

[inspectorK]

Chris,
I also just noticed and figured I would make you aware (even though you probably already are) that this issue is the same as: #18 which was abandoned about a year ago after no response. However, I do believe this would be helpful to at least provide an option to force newline formatting if desired.