PowerShell V2 – External MAML Help

PowerShell Team

As you’ve probably picked up by now – Advanced Functions are super important. We’ve been showing a bunch of scripts that have embedded help using comments and dot-tags. Let me take a second and drill into this.

We believe that PS will be used in a wide range of; scenarios: simple one liners; personal ad hoc scripts; scripts you share with your friends; scripts you share with the community; scripts you in your commercial product. It is our goal to have a single mechanism with progressively richer and richer optional features to support this entire range of scenarios. We’ve been showing you the Community Help experience but we have also designed it so that commercial products can ship PS scripts. In particular, we support the ability to have external MAML help which can be localized into multiple languages. This is not implemented in CTP3 but we expect to support it in V2.

Below is an excerpt from Refaat Issa’s spec.

Enjoy!

Jeffrey Snover [MSFT] Windows Management Partner Architect Visit the Windows PowerShell Team blog at: http://blogs.msdn.com/PowerShell Visit the Windows PowerShell ScriptCenter at: http://www.microsoft.com/technet/scriptcenter/hubs/msh.mspx

External MAML Help

When a full-fledged MAML file is required, or when localization into other languages is essential, a script author can add external MAML help to a function.

Traditionally, MAML help files for cmdlets were packaged in the snap-in, along with the cmdlets themselves. The snap-in installation process placed the MAML files into the folder $pshome\en-US. The culture-specific folder (en-US) varies according to the operating system’s UI culture.

Functions should not use the same folder to place their MAML files because $pshome requires administrative rights, which the script author may not have. However, the Get-Help language folder hierarchy and fallback mechanism will be used for functions as well. Syntax: .ExternalHelp C:\MyScripts\MyHelpfile.xmlThe external MAML help file name & path are indicated in the ExternalHelp inline help directive.

The argument value (C:\MyScripts\MyHelpfile.xml) is resolved in the following order:

• The file name is separated from the rest of the path. This path becomes the starting folder. (C:\MyScripts)
• The help system searches for a folder bearing the name of the operating system’s UI culture, such as “en-US” or “de-DE”, under the starting folder. (C:\MyScripts\de-DE)
• If the specified MAML file is not found, then the “Vista language fallback” logic is applied and the help system searches for a folder bearing the fallback language name, such as “en” or “de”. (C:\MyScripts\de)
• If the MAML file is still not found, then the starting folder is searched for the MAML file. (C:\MyScripts\MyHelpFile.xml)

Notes:

• Spaces are allowed in the help file path
• .ExternalHelp can exist on its own as inline help, without the need for Synopsis … etc.

PowerShell Team PowerShell Team, PowerShell

Follow