The current platyps schema for Examples allows the following:
## Examples
### Example 1
0 or more paragraphs
1 or more code blocks
0 or more paragraphs
When the markdown is converted to MAML, only the paragraphs after the code blocks are written to the MAML file.
The problem is that most of our help content has been updated to use the pattern shown above.
Example case
I have the following example in markdown.
### EXAMPLE 3 - Run only the DSC rules with the Error severity
This example runs only the DSC rules with the Error severity on the files in the **MyDSCModule**
module.
```powershell
$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where-Object SourceName -eq PSDSC
$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule\*"
Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse
```
Using the **IncludeRule** parameter of `Invoke-ScriptAnalyzerRule` is more efficient than using its
**Severity** parameter, which is applied only after using all rules to analyze all module files.
The MAML that is produced contains:
<command:example>
<maml:title>-- EXAMPLE 3 - Run only the DSC rules with the Error severity --</maml:title>
<dev:code>$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where-Object SourceName -eq PSDSC
$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule\*"
Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse</dev:code>
<dev:remarks>
<maml:para>Using the IncludeRule parameter of `Invoke-ScriptAnalyzerRule` is more efficient than using its Severity parameter, which is applied only after using all rules to analyze all module files.</maml:para>
</dev:remarks>
</command:example>
Notice that the <dev:remarks> element only contains the paragraph after the code block.
Suggested fix
New-ExternalHelp should create a <dev:remarks> element for every paragraph in the example. Inside the <command:example> element the <dev:remarks> and <dev:code> elements should be ordered as written in the markdown.
Proof of concept
I edited the MAML file to add the missing paragraph:
<command:example>
<maml:title>-- EXAMPLE 3 - Run only the DSC rules with the Error severity --</maml:title>
<dev:remarks><maml:para>This example runs only the DSC rules with the Error severity on the files in the **MyDSCModule** module.</maml:para></dev:remarks>
<dev:code>$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where-Object SourceName -eq PSDSC
$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule\*"
Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse</dev:code>
<dev:remarks>
<maml:para>Using the IncludeRule parameter of `Invoke-ScriptAnalyzerRule` is more efficient than using its Severity parameter, which is applied only after using all rules to analyze all module files.</maml:para>
</dev:remarks>
</command:example>
Now Get-Help displays both remarks (though not in the written order).
PS C:\Git> (Get-Help -full Get-ScriptAnalyzerRule).examples.example[2]
-- EXAMPLE 3 - Run only the DSC rules with the Error severity --
$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where-Object SourceName -eq PSDSC
$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule\*"
Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse
This example runs only the DSC rules with the Error severity on the files in the **MyDSCModule** module.
Using the IncludeRule parameter of `Invoke-ScriptAnalyzerRule` is more efficient than using its Severity parameter,
which is applied only after using all rules to analyze all module files.
Get-Help and the HelpInfo object model need to support this better.
The problem
The current platyps schema for Examples allows the following:
When the markdown is converted to MAML, only the paragraphs after the code blocks are written to the MAML file.
The problem is that most of our help content has been updated to use the pattern shown above.
Example case
I have the following example in markdown.
The MAML that is produced contains:
Notice that the
<dev:remarks>
element only contains the paragraph after the code block.Suggested fix
New-ExternalHelp
should create a<dev:remarks>
element for every paragraph in the example. Inside the<command:example>
element the<dev:remarks>
and<dev:code>
elements should be ordered as written in the markdown.Proof of concept
I edited the MAML file to add the missing paragraph:
Now
Get-Help
displays both remarks (though not in the written order).Get-Help
and the HelpInfo object model need to support this better.