Powershell V2 External MAML Help

Question

I'm trying to create an external MAML help file for a script Module. As a test I created a simple module called "ModTest" with 2 functions saved in a .psm1 file:

function Test-SqlScript2 
{
}
function Out-SqlScript2
{
}

I saved the module in my user Modules directory ~\Documents\Modules\ModTest Next I created a subdirectory for a MAML file ~\Documents\Modules\ModTest\en-US The MAML file I'm using for testing is available here. I then started PowerShell and used Import-Module to import the module.

Unlike compiled cmdlets the placement of the file does not work by itself

So, next I tried adding the help link to the top of the script module, which also doesn't work:

<#
.ExternalHelp C:\Users\cmiller6\Documents\WindowsPowershell\Modules\ModTest\en-US\ModTest.help.xml 
#>


function Test-SqlScript2 
{
}
function Out-SqlScript2
{

Then I tried adding the help info to each function, which does work:

function Test-SqlScript2 
{
<#
.ExternalHelp C:\Users\cmiller6\Documents\WindowsPowershell\Modules\ModTest\en-US\ModTest.help.xml 
#>
}
function Out-SqlScript2
{
<#
.ExternalHelp C:\Users\cmiller6\Documents\WindowsPowershell\Modules\ModTest\en-US\ModTest.help.xml 
#>

Two questions:

1. Is it possible to create a script module level external MAML help OR do you need to specify the help link in each function?
2. Although the documentation claims and blog posts indicate that the language specific folder i.e. en-US will be automatically searched when specifying a path (~/ModTest\ModTest.help.xml) I could not get the MAML file to resolve unless I included the explicit path (~/ModTest/en-US/ModTest.help.xml). Is this a bug? See the following links for documentation on get-help and language specific folders:

Writing Help for Windows PowerShell Modules PowerShell V2 External MAML Help

Answer 1

Regarding #1, it appears to me that you have to specify the ExternalHelp comment tag for each command (script or function). Update: I got confirmation from the PowerShell team that you have to specify the comment tag for each command. I submitted a suggestion on MSConnect that you can vote on if you would like to see this in a future version of PowerShell.

Regarding #2, it does work and from my testing you don't have to specify the full path (which is very nice). Here are the contents of the module dir I created to test this:

~\Documents\WindowsPowerShell\Modules\ModTest\ModTest.psm1
~\Documents\WindowsPowerShell\Modules\ModTest\en-US\ModTest.psm1-Help.xml
~\Documents\WindowsPowerShell\Modules\ModTest\fr-FR\ModTest.psm1-Help.xml

The contents of my ModTest.psm1 file is:

#  .ExternalHelp ModTest.psm1-Help.xml
function Add-BitsFile([object[]]$BitsJob, [string[]]$Destination, 
                      [string[]]$Source)
{
    Write-Host "Add-BitsFile"
}

#  .ExternalHelp ModTest.psm1-Help.xml
function Complete-BitsTransfer([object[]]$BitsJob)
{
    Write-Host "Complete-BitsTransfer"
}

The two ModTest.psm1-Help.xml files are just a copy of:

"$pshome\Modules\BitsTransfer\en-US\Microsoft.BackgroundIntelligentTransfer.Management.dll-Help.xml"

The biggest PITA in testing this out was to get a valid MAML file so I just copied a known working file. :-) BTW for the French version I just prefixed the synopsis with "Parlez vous" so I could test that it worked.

Next up, you need a quick way to change the thread currentUICulture to test the different, localized help files. This is a function Jeffrey Snover wrote some time ago. I updated it to also change the CurrentUICulture:

function Using-Culture (
[System.Globalization.CultureInfo]$culture = `
    (throw "USAGE: Using-Culture -Culture culture -Script {scriptblock}"),
[ScriptBlock]$script= `
    (throw "USAGE: Using-Culture -Culture culture -Script {scriptblock}"))
{
    $OldCulture = [System.Threading.Thread]::CurrentThread.CurrentCulture
    $OldUICulture = [System.Threading.Thread]::CurrentThread.CurrentUICulture
    try {
        [System.Threading.Thread]::CurrentThread.CurrentCulture = $culture
        [System.Threading.Thread]::CurrentThread.CurrentUICulture = $culture
        Invoke-Command $script
    }
    finally {
        [System.Threading.Thread]::CurrentThread.CurrentCulture = $OldCulture
        [System.Threading.Thread]::CurrentThread.CurrentUICulture = $OldUICulture
    }    
}

Now let's test it:

PS> gmo|rmo
PS> ipmo ModTest
PS> Add-BitsFile -?

NAME
    Add-BitsFile

SYNOPSIS
    Adds one or more files to an existing Background Intelligent Transfer 
    Service (BITS) transfer job.

<snip>

PS> using-culture fr-FR {gmo|rmo; ipmo ModTest; Add-BitsFile -?}

NAME
    Add-BitsFile

SYNOPSIS
    Parlez vous adds one or more files to an existing Background 
    Intelligent Transfer Service (BITS) transfer job.