Add "powershell" label to examples markdown

[brianlic-msft]

Upon moving to docs.microsoft.com, we've been asked to add "powershell" to the opening code block of each example. Is it possible to do this so all new cmdlets have it by default?

Here's an example before:

EXAMPLES

Example 1: Add AIA to the specified authority

PS C:\> Add-CAAuthorityInformationAccess -AddToCertificateAia -Uri http://ca1.corp.contoso.com/pki

And here's an example after:

EXAMPLES

Example 1: Add AIA to the specified authority

PS C:\> Add-CAAuthorityInformationAccess -AddToCertificateAia -Uri http://ca1.corp.contoso.com/pki

[vors]

Hi @brianlic-msft

Thank you for the suggestion. I had a conversation about it with @juanpablojofre and other tech writers. I see that this topic created a lot of confusion, so let me write down my thinking and maybe open a discussion about it.

This "powershell" language moniker is called info-string in the commonmark spec. It says:

The first word of the info string is typically used to specify the language of the code sample, and rendered in the class attribute of the code tag. However, this spec does not mandate any particular treatment of the info string.

My interpretation of it is that code inside the code block should be a syntactically valid program in this language.

Practically, you should be able to copy-paste this program.

The traditionally used PS C:\> preambula is what makes me uncomfortable with putting language moniker by default in the examples.
If you combine input string and the output result of it in the same code-snippet, this problem becomes more apparent.

To workaround this problem, I implemented support for multiply code blocks inside one example.
This somewhat cumbersome part of the schema explains it

    // one or more times, codesnippet
    // it's useful to put the ```powershell code
    // before the plain text command exectution output
        ```{Syntax language, i.e. PowerShell or nothing for plain text}
        {{Example body}}
        ```

To summarize

1. In my opinion language moniker and PS C:\> cannot be used together, because it's misleading
2. All existing powershell help used PS C:\>, that's why the default is not to put a moniker, so it's easier to recognize the pattern for new users.
3. When language moniker is used, the PS C:\> part should be removed. Note that this will also affect the generated maml. Alternative to auto-add PS C:\> to all examples on maml generation is too much, not intuitive and will lead to more confusion.
4. There is an implemented way to combine valid ps syntax with moniker and output of the command (without moniker) but it's not very well known and used.

Since this topic been a big source of confusion for a long time, I see a need of making guidelines about examples code snippets clearer. There are few competing goals:

1. Make use of syntax highlighting in the example.
2. Preserve the familiar format PS C:\> in the generated maml
3. Desire to have a clean and valid syntax in the markdown code snippets.

More I think about it, more I agree that we should sacrifice number 3 and use the following format:

PS C:\> New-AwesomeCommand -With -All -Arguments

Output of my awesome command

This way

1. we use syntax highlighting were it's needed, with a tiny incorrectly highlighted PS C:\>
2. Have a clear separation of command and commands output.

[BernieWhite]

Currently if the ```powershell syntax is used it will be removed by Update-MarkdownHelp.

[vors]

@BernieWhite good catch

[BernieWhite]

Following on, for SYNTAX sections there should be no reason why the ```powershell fenced should not be the default.

[vors]

I cannot agree with that

The first word of the info string is typically used to specify the language of the code sample, and rendered in the class attribute of the code tag. However, this spec does not mandate any particular treatment of the info string.

My interpretation of it is that code inside the code block should be a syntactically valid program in this language.

The SYNTAX is not a valid program in powershell and hence it would not benefit from the syntax highlighting. It's possible to find some other highlighting moniker that can produce a reasonable results, but I don't see any reason why it would be powershell.

To illustrate it, let's take a look at example

Plain text

Merge-MarkdownHelp [-Path] <String[]> [-OutputPath] <String> [-Encoding <Encoding>] [-ExplicitApplicableIfAll]
 [-Force] [[-MergeMarker] <String>] [<CommonParameters>]

Powershell

Merge-MarkdownHelp [-Path] <String[]> [-OutputPath] <String> [-Encoding <Encoding>] [-ExplicitApplicableIfAll]
 [-Force] [[-MergeMarker] <String>] [<CommonParameters>]

Bash

Merge-MarkdownHelp [-Path] <String[]> [-OutputPath] <String> [-Encoding <Encoding>] [-ExplicitApplicableIfAll]
 [-Force] [[-MergeMarker] <String>] [<CommonParameters>]

Haskell

Merge-MarkdownHelp [-Path] <String[]> [-OutputPath] <String> [-Encoding <Encoding>] [-ExplicitApplicableIfAll]
 [-Force] [[-MergeMarker] <String>] [<CommonParameters>]

Scala

Merge-MarkdownHelp [-Path] <String[]> [-OutputPath] <String> [-Encoding <Encoding>] [-ExplicitApplicableIfAll]
 [-Force] [[-MergeMarker] <String>] [<CommonParameters>]

js

Merge-MarkdownHelp [-Path] <String[]> [-OutputPath] <String> [-Encoding <Encoding>] [-ExplicitApplicableIfAll]
 [-Force] [[-MergeMarker] <String>] [<CommonParameters>]

It looks like JS is actually looks better on average, should we then use it?
It may look more colorful, sure, but it doesn't enhance the reading of this doc string.

[BernieWhite]

@vors Thanks. I see your point.

[BernieWhite]

Further thought on this one, does the prefix PS C:\> change if PowerShell / platyPS is on a different platform?

[vors]

Hmm, good point.
I think we should raise this question in https://github.com/PowerShell/PowerShell-Docs regarding the https://github.com/PowerShell/PowerShell-Docs/tree/staging/reference/6 content. Since 6 is multi-platform, but it still uses the PS C:\> convention.
I'm not a technical writer and I think this should be tech write call.

[BernieWhite]

I'll have a look at this one.

I noticed, if we currently have two separate code blocks defined under the one example like below, they will merge together into a single block during Update-MarkdownHelp.

PS C:\> New-AwesomeCommand -With -All -Arguments

Output of my awesome command

i.e.

PS C:\> New-AwesomeCommand -With -All -Arguments

Output of my awesome command

Based on the discussion above we will need to keep the blocks separated in markdown.

Thoughts on Yaml. Is it ok to aggregate the multiple code blocks like the existing markdown implementation when generating yaml output?

platyPS/src/Markdown.MAML/Transformer/ModelTransformerBase.cs

Lines 181 to 191 in ffd067e

	while ((codeBlock = CodeBlockRule()) != null)
	{
	if (example.Code == null)
	{
	example.Code = codeBlock.Text;
	}
	else
	{
	example.Code += "\r\n\r\n" + codeBlock.Text;
	}
	}

[vors]

Oh good catch!
I think it's unintentional bug: the code to merge the examples was added before support for multiply code snippets in the schema and parser to handle existing maml. So we should just fix it and start treat it as a list of code snippets instead. Possibly can add a language moniker field, preserve it for updates and guess it based on a some heuristic for existing maml.