Make it easier to provide multilingual help and help for binary cmdlets
Writing MAML help is hard. There are some editors which make it easier, but nothing that really fits our needs. Sapien's editor is pretty good, but when you look at the changes it makes in a diff tool, it's hard to rationalise that with the buttons you clicked.
Some possible options include:
* More / better / simpler choices for the format of the help. Simpler XML, simple JSON, simple Markdown, simple comment-based help.
Better editors in VS and the ISE
Scaffold cmdlets to help you generate the MAML code
My personal favourite is allowing the comment-based help to be provided separately from the cmdlet and have it loaded appropriately for the correct cmdlet and language using resource resolution rules similar to .NET.
For example, I could have this in my module folder:
If the system locale is English, or specific resources have not been provided for the system locale, the root one is loaded. If the locale has been provided, then the appropriate help file is loaded.
The contents would the name of a cmdlet, followed by the comment-based help, for each cmdlet in the module.
platyPS will do the job. Sapien has an excellent GUI tool (The PowerShell Help Writer) to bulk-convert entire modules' help.
Finally, here's a blog post of mine on multilingual help:
A more userfriendly native way would be nice, but those are the best alternative solutions I have found so far.
John Ludlow commented
Sure, that would solve the problem too.
I've since become aware of https://github.com/PowerShell/platyPS - maybe that is the answer
Thomas Lee commented
Rather than provide assistance with MAML, why not create a Comment-based Help to MAML converter. If you think about it, PowerShell already knows how to parse the CBH blocks into something close to MAML. Why not a built in ultility to take the CBH in a file and produce a ready to go MAML equivalent.