We should have a separate cmdlet to upgrade from old version of schema to a new one.

• Fix all issues
• Make a release to PSGallery
• Update PSReadLine

Hyperlinks currently handed far from perfect.

• Our pattern uses @"\[(.+?)\]\((https?://[^'\"">\s]+)?\)" regex to recognize them. It would not treat relative github links as hyper-links.
• After a full circle unrecognized link would gain additional escaping, so it would be rendered improperly

Filenames need to have the full XML filename that is compatible all the way to PS 3.0. This differs across script, binary, CDXML, and provider cmdlets.

This API is an implementation detail and not interesting for the end users.
Lets remove it.

Note: our test infrastructure still may want to use it. We can use & (Get-Module platyPS) {..} workaround to enable it.

Add the ability to compress prepared help files to a cabinet. This enables the creation of downloadable packages that can be used with Update-Help. Use MakeCab.exe as it is commonly available on Windows operating systems.

New Functionality - New-PlatyPsCabinet

Add a script cmdlet to platyPs that will utilize the makecab.exe to compress target files into a cabinet.
The name of the cab which must be particular for the PowerShell help engine to find and extract, will be based on the params provided for Module Name, GUID, and Locale.

Required Params

In order to correctly name a cab

    [Cmdletbinding()]
    param(
        [parameter(Mandatory=$true)]
        [string] $Source,
        [parameter(Mandatory=$true)]
        [string] $Destination,
        [parameter(Mandatory=$true)]
        [string] $Module,
        [parameter(Mandatory=$true)]
        [string] $Locale,
        [parameter(Mandatory=$true)]
        [string] $Guid
    )

Source

The source directory containing all of the files to be added to the cab. Non-Recursive.

Destination

The output directory to create the cab file. It should create a reusable folder structure:

\CabFile\
           \datetime cmdlet was run\
           \latest\

This folder structure will allow the output to be added to the latest folder, as well as a time stamped directory for historical purposes.

Module

The name of the module as it appears in the PowerShell console when Get-Command -ListAvailable is run.

Locale

The language code the of the help the cab will contain:
xx-XX format, ie: en-US or fr-FR or es-ES

Guid

The GUID of the PowerShell module.
Typically alphanumeric XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Module Naming Convention

The help system in PowerShell requires that Cabs have a specific name scheme in order for Update-Help to find the package, download, and extract it.

<ModuleName>_<ModuleGuid>_<Locale>_helpcontent.cab

Output

Using the destination param, the cab file will be output to a target destination.

After a conversion of module to MD, the folder has '.md' i.e. file name is empty.

• Finalize on cmdlet Template - Issue #34 - Complete by April 14
• Updating published Markdowns with new code changes in the PS Module -Issue #38 - Complete by May 13
• Need a solution to generate Providers and About - Issue #37 - Complete by June 3
• Add cabinet creation cmdlet to PlatyPS - Issue #35 - Complete by April 22
• Add help.xml proper naming conversion cmdlet to PlatyPS - Issue #36 - Complete by May 10
• Add metadata block support (for BI) in the schema - Completed
• Add cmdlet for upgrade from schema - Issue #49 - Complete by May 13

Creating this issue to ensure we test this functionality
When get-help is run against a cmdlets, if the -online parameter is used, an web page will be opened where the published version of the help can be seen.

The link data is available in the related links section, but the documentation authors need to be sure this will work once the conversion from MD to MAML is performed.

Get-Help Add-Computer -online
#links to: 
#https://technet.microsoft.com/library/712f3460-c5d0-4af8-8de6-6d06e4a1a838(v=wps.630).aspx

This link, is stored in the MAML related links section here, note the Online Version text:

    <maml:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version:</maml:linkText>
        <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=290488</maml:uri>
      </maml:navigationLink>
    </maml:relatedLinks>

It's easy to implement, but we really need it.
Arbitrary grouping would allow somebody to group cmdlets by the meaning inside one dll.

Before:

ScriptBlock

The ScriptBlock is called when the Chord is entered. The ScriptBlock is passed one or sometimes two arguments. The first argument is the key pressed (a ConsoleKeyInfo.) The second argument could be any object depending on the context.

Type: ScriptBlock
Parameter Sets: Set 1
Aliases: 

Required: True
Position: 1
Default value: 
Accept pipeline input: false
Accept wildcard characters: False

After:

-ScriptBlock

The ScriptBlock is called when the Chord is entered. The ScriptBlock is passed one or sometimes two arguments. The first argument is the key pressed (a ConsoleKeyInfo.) The second argument could be any object depending on the context.

Type: ScriptBlock
Parameter Sets: Set 1
Aliases: 

Required: True
Position: 1
Default value: 
Accept pipeline input: false
Accept wildcard characters: False

What do you think? We need to make a decision by Tuesday

I think current name looks pretty unfun.
I'd like to drop platyPS prefix and do other small tweaks.

• Get-PlatyPSMarkdown -> New-Markdown (semantic changed after #51, so verb change)
• Get-PlatyPSYamlMetadata -> Get-MarkdownMetadata
• Get-PlatyPSExternalHelp -> New-ExternalHelp (we want to embeed information about naming convention in markdown metadata, so semantic would change: it would drop a file on the disk)
• Get-PlatyPSTextHelpFromMaml -> Show-HelpPreview
• New-PlatyPSCab -> New-ExternalHelpCab
• Format-PlatyPsHelpXml -> $null (we will spreed this functionality across New-ExternalHelpCab and New-ExternalHelp)
• new cmdlet from #49 -> Update-Markdown

cc @jongeller

Currently we escape < and > as \< and \>, but we don't correctly handle \foo\bar\<baz>\foo case.

Can we support tables for parameters metadata?

Suggestion come from June.
Huge chunks of text are unappealing in the raw view.

New-Markdown should have -OnlineHelp (issue #58 )

This is far in the future, but I want to capture this idea now.

There are write-only scenarios for generated markdown:
Examples:

• github wiki ( issue #69 )
• DocFX docs with cross-references

It may be desirable to customize them somehow. I.e. do post-processing on cross-references to link them appropriately.

Something to have in mind for future.

Before next release

• src\platyPS\docs
• README.md with updated scenarios

This is to take new syntactical updates (e.g. a new parameter) to already-documented cmdlets in the Markdown file.

MarkdownStringToMamlString must be fast (less then a minute for this file)

$markdown = cat .\Examples\SMA.Help.md -Raw
$generatedMaml = [Markdown.MAML.Renderer.MamlRenderer]::MarkdownStringToMamlString($markdown)

https://ci.appveyor.com/project/lzybkr/psreadline/build/1.0.13

in platyPS.schema.md, {Input type} is preceded by four #, where I would have expected the nesting level to be at three #, as is the case for {Parameter name}, {Output type} and {Example Name}.

Is this a design choice or a nesting error introduced in bbeba47?

I have a function that has a dynamic param set, and there is a switch that is not mandatory, but it is not explicitly set to false, and the markdown outputs Mandatory as true. If I add Mandatory = $false it will output correctly, so I am guessing it is just defaulting to $true?

*edit
this only seems to happen on param of Type Switch, i have a String param, that one is also not mandatory, and not explicitly defined as such, but it outputs as mandatory: False.

Since, there Get-Help output contains a bunch of [PSObject] with NoteProperties, it's much simpler to do it in PS then in C#.

This is what I get:

107> $generatedModule.Cmdlets | % { Get-Help -Name "$($generatedModule.Name)\$_" -Full | Out-String }
Get-Help : Get-Help could not find testplay.psm1-Help.xml_2139322656\Edit-File in a help file in this session. To
download updated help topics type: "Update-Help". To get help online, search for the help topic in the TechNet library
at http://go.microsoft.com/fwlink/?LinkID=107116.
At line:1 char:32
+ ... dlets | % { Get-Help -Name "$($generatedModule.Name)\$_" -Full | Out- ...
+                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ResourceUnavailable: (:) [Get-Help], HelpNotFoundException
    + FullyQualifiedErrorId : HelpNotFound,Microsoft.PowerShell.Commands.GetHelpCommand

Could it be that your example is working because you're working in the platyPS out dir (where there is a real module)?

Need a solution to address this Scenario:

We have markdown files for a module already published. Module gets updated with either a new cmdlet or changes to parameters for an existing cmdlet. How do we get the published markdowns updated with the new changes.

Requirement from @sankethka

There are common parameters in PowerShell.

There is a content help difference between v4 and v5

> (Get-Help Add-Computer).syntax.syntaxItem[0].Parameter.Name | ? {$_ -like 'info*'}
# in v5
InformationAction
InformationVariable
# in v4 nothing

To resolve it properly, I'd like to rise a conceptual question:
Is it a legitimate scenario to include explicit entry about particular common parameter in help?

when using the New-Markdown cmdlet, the inputs or outputs are not being populated (using a build as 2016-05-16, 9:11 EST).

I am digging into the code to see if i can determine why.

Tool is not ready, until it cannot be used to work on itself.

It's not easy to distinguish a start of a new command.
We need to make it obvious.
I.e. we can use plenty of padding and ------ lines.

yesterday, my dynamic parameter sets where getting exported in New-Markdown, but this is no longer happening as of building this morning.

There is a special attribute [SupportsWildcards()] to achive what I did with a string* hack.
Unfortunately, looks like I cannot parse out this info (globbing) from the snippet.

Scenarios:

• Verify that markdown is compliant with schema
• Verify / report that all text fields are filled (i.e. NOTES, description placeholders)

Scenarios to consider:

• Verify markdown metadata keys. It's needed for a large scale pipelines, i.e. if MS adopts platyPS. Maybe create a Test-MarkdownMetadata instead?

This is the initial generation of "stub reference" documentation in Markdown for a new module.

Scenario here is to first finish the module and then to generate documentation for later annotation.

This is to ensure that the syntax, parameters, etc. (syntax goo) actually matches what is in the module.

Per discussion in #20 , everybody agreed that it's a good idea to enforce one cmdlet per file policy for the help. Hence, we should make it the default.

I would not pull out support for multiply cmdlets in the same file, but an APIs to bootstrap such markdown would be de-promoted from default to exotic.

Syntax has to be generated from parameters description, without an explicit entries in markdown.

Currently there is no way to speficy that parameter is mandatory, belongs to a ParameterSet and so on.

In Microsoft, it's a common practice to provide a VM with installed module to a techwriter.
We should support remote execution for scale.

Hello! This tool looks great, and I plan to use this to help automate my github wiki very soon! However, I see in the newest version (from the repo, not from the PoSh Gallery) that the New-Markdown shows a header, even on your pages. For instance:

---
external help file: gShell.dll-Help.xml
schema: 2.0.0

---

At the very least can this be moved to the bottom and/or become optional with a switch like you'd see with Export-Csv -NoTypeInformation?

I'm hip deep in things at the moment, but I can look in to making a pull request sometime this week if that would make things any faster.

Thanks for your consideration!

We need to create a markdown file that summarizes all of the cmdlets in the module. It will also contain the metadata at the module level that is required for creating a cab.

Here is the example:
Windows PowerShell Management Cmdlets - Landing Page

We need, at least:

For the Cab

• Module Name
• Module GUID

For the HelpInfo

• FW Link to the cab help package for downloading in updateable help
• Help Version
• Locale

Yeah, I "could" use:

$maml = Get-platyPSExternalHelp -Markdown (gc -raw myhelp.md)

but I'd rather use:

$maml = Get-platyPSExternalHelp -MarkdownFilePath myhelp.md

Add a cmdlet to PlatyPs the properly names a help.xml file for use.
Help files need to be specifically named in order for the PowerShell help engine to find them. There must be a help file corresponding to each cmdlet-providing code file, DLL, CDXML, PSM1.

New Functionality - Format-PlatyPsHelpXml

This cmdlet will take the name of a file that contains the code for a Powershell module's cmdlets. It will also take in the source help.xml file. Using these two things, the cmdlet will generate a help.xml file that is properly named and can be consumed by the PowerShell help engine.

Required Params

[Cmdletbinding()]
    param(
        [parameter(Mandatory=$true)]
        [string] $HelpFileSourceXml,
        [parameter(Mandatory=$true)]
        [string] $ModuleFileName,
        [parameter(Mandatory=$true)]
        [string] $Destination
    )

File naming convention

The help system in PowerShell requires that help.xml files have a specific name scheme in order for Get-Help to find the documentation and display it in the help console.

<ModuleCodeFileName>-help.xml

This ask was split later, in thread, keep reading....
PlatyPS doesn't yet have a solution to generate providers data. Need a solution in place to handle this content.

On the line 871, there is a special symbol $text -replace '–','-'
It's parsed incorrectly, when locale is not en-US.