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.

[BernieWhite]

@vors Thoughts on info-string for output blocks?

Schema says don't use an info-string for output blocks. From a implementation point of view it makes sense to only detect language based on blocks that do not already have an info-string. Meaning output blocks might incur a slightly higher cost for each Update-MarkdownHelp pass.

My preference would be to use an info-string of text for output blocks and have the language detected once.

This aligns to PS docs style guide as per MicrosoftDocs/PowerShell-Docs#1511.

[BernieWhite]

The query into how prompts are handled from documentation (particularly relating to cross-platform scenarios) resulted in a link to this document (brand new guidance).

https://github.com/PowerShell/PowerShell-Docs/blob/staging/contributing/FORMATTING-CODE.md

From the document both PS C:\> and PS> are prompt indicators. Although the PS> seems to be the recommended going forward.

We should include at least PS C:\> and PS> in heuristics detection of PS code blocks.

We should also allow for customising the default info-string for non-PS detected blocks. So default to no info-string, then if a block hasn't been detected as PS use the custom info-string if set.

[sdwheeler]

Our current style says that Examples should use the powershell label but syntax blocks should not.

[chscott]

Our current style says that Examples should use the powershell label but syntax blocks should not.

Note that this has implications for anyone using a Markdown linter like markdownlint.

The reasoning for stripping the language specifier from the SYNTAX section is an academic one and not a practical one.

[sdwheeler]

This is fixed in Microsoft.PowerShell.PlatyPS v1 for examples. We don't add a language to the syntax blocks because they are not powershell language. The syntax highlighting does not apply to them.