PowerShell Feature Request: Extended PowerShell type for Help Topics data

I’ve spend a lot of time over the past 6 months exploring the PowerShell help system and the objects it exposes in great detail.  Part of this was to learn PowerShell, and part of this was to get the information I needed for my Integrated PowerShell Help PowerPack for PowerGUI.  While doing this work, it was really clear how much value is added by having the help system accessible through PowerShell itself (more on that in another post).  But there was one small thing that seemed lacking in the first implementation of the help system, hence this feature request.

I’d like to request that the help information for general topics (Get-Help -Category HelpFile) be defined as rich .NET objects similar to MamlCommandHelpInfo.  Currently when you pull up help for a general topic, the object you get back is of type System.String.  This can be seen through the following script:

Get-Help about_alias | Get-Member

This string contains the contents of the file corresponding to the general topic you requested help information for, and if you have the PowerShell Multi User Interface Language Pack installed it will be in the language of the current PowerShell session.  This differs from the other help in PowerShell, such as help for cmdlets.  When you pull up help for a cmdlet, the object you get back is of type MamlCommandHelpInfo.  This can be seen through the following script:

Get-Help Get-Command | Get-Member

This will also be displayed in the language of the current PowerShell session, however there is an important distinction between this and the help information returned for general topics.  In general day-to-day use within PowerShell you won’t notice the difference because when you request this help information it is simply returned to you in the console.  Where the difference becomes apparent is when you’re using PowerShell script to access help information, you want that script to support all languages that PowerShell has been localized to, and you want to format it differently or you want to extract a subset of the documentation from it.

If you’re reading help documentation for cmdlets from PowerShell using PowerShell script, the object returned has properties containing each of the sections you would see when requesting full help information (e.g. Get-Help Get-Command -Full).  This includes Name, Synopsis, Syntax, Detailed Description, Parameters, Input Type, Return Type, Remarks, Examples and Related Links.  Writing a script for this that supports localized versions of PowerShell is facilitated through the use of these parameters because you can get each separate part of the documentation in the language of the PowerShell session programmatically.

If you’re doing the same thing for general topics, you can’t access the different sections of the help documentation because you don’t have rich .NET objects containing properties with the different.  Instead you have to parse the documentation programmatically, which isn’t too difficult in Western languages but including support for Eastern languages becomes quite a challenge, to say the least.

Having the help documentation for general topics returned as objects similar to MamlCommandHelpInfo would make life much easier when supporting multiple languages while accessing this documentation using PowerShell scripts.  This isn’t very high on my priority list, but it would definitely be nice to have.

Kirk out.

Technorati Tags: PowerGUI, PowerShell, PoSh, Poshoholic
Add to: | Technorati | Digg | del.icio.us | Yahoo | BlinkList | Spurl | reddit | Furl |