Windows PowerShell Graphical Help File
Readme
This is the readme that goes along with the Windows PowerShell Graphical Help File. This readme will become much more helpful if you actually download the Help file that goes with it.
|
On This Page
 | Windows PowerShell Graphical Help File: Readme |
| Announcing the Windows PowerShell Graphical Help File |
| But I Like to Type! |
| A Final Thought or Two |
Windows PowerShell Graphical Help File: Readme
You know what? Nothing is perfect. And, believe it or not, that includes Windows PowerShell.
Not that Windows PowerShell – Microsoft’s new command shell and scripting environment – isn’t a very cool technology; it is. Nevertheless, PowerShell does have at least one weakness: its help system. Granted, it’s great that PowerShell even has a help system. And there’s nothing wrong with the help topics themselves; in fact, these are actually pretty darn good, not only explaining the conceptual basis for Windows PowerShell commands and cmdlets but also featuring plenty of examples that show you how to put these commands and cmdlets to work. Unfortunately, though, a few … idiosyncrasies … with the help engine might prevent you from realizing just how useful Windows PowerShell help really is.
What kind of … idiosyncrasies? Well, for one thing, the default behavior of the Get-Help cmdlet (the cmdlet used to access help topics) is to show you just a smidgen of the information that’s available for a topic. For example, suppose you type the following at the Windows PowerShell prompt:
Get-Help Get-ChildItem
Will you get back information about Get-ChildItem? You bet you will. However, the information you get back will be somewhat cursory, little more than a syntax diagram and a description. To get detailed information about Get-ChildItem (including information about the parameters available to this cmdlet and examples that show you how to actually use Get-ChildItem) you need to add the –detailed parameter, like so:
Get-Help Get-ChildItem -detailed
Confusing? Yes, a little bit, especially for beginners.
Admittedly, though, that’s not too bad; just one extra thing to remember and type. (Although it would be nice if the default behavior was to show you all the help rather than just a small portion of the help.) Unfortunately, though, there are a few other problems that you have to overcome. For example, the help engine doesn’t break words properly at the end of a line; take a close look at the following screenshot (in particular, take a peek at the end of each line) and you’ll see what we mean:
Click here for a full-size version of this image.
What a coincidence: that’s exactly what we said the first time we saw this!
And, of course, any time you call Get-Help the help topic quickly scrolls past you onscreen; you then need to scroll back up to get to the beginning. (Although you can circumvent that problem by using a command similar to this when using help: Get-Help Get-ChildItem -detailed | Out-Host –paging). Let’s see, what else? The topics include related links that aren’t really links (at least not in the sense that you can, say, click one of these links and quickly and easily access those related topics); you can’t (without writing some custom code) do a full-text search on the entire help system; this help, good as it is, is only available when PowerShell is up and running; and so on. None of that makes PowerShell help unusable and, like we said, the quality of the help itself makes up for most of these shortcomings. But, still ….
On the other hand, PowerShell help is what it is, and there really isn’t much you can do about it, is there?
Honestly, we don’t know whether there’s much you can do about it. But that doesn’t matter, because you don’t have to do anything about it: the Scripting Guys have already done it for you.
Announcing the Windows PowerShell Graphical Help File
To tell you the truth, the Windows PowerShell Grapical Help File is just a high-falutin’ name for a very simple idea: all we did was export the Windows PowerShell help topics (including both the cmdlet help and the “About” topics) and turn each of those items into a separate HTML page. We then cleaned up the formatting a bit, added a hyperlink here and there, and even stuck in a few links to additional resources. (Sure, most of these are simply advertisements for – or, um, links to – the Script Center. But, hey, who did all the work here?!?) We then took all those HTML pages and rolled them up into a graphical help file named PowerShell.chm. Remember the help for Get-ChildItem that we showed you a minute ago? Here’s what that same help topic looks like in the graphical help file:
Click here for a full-size version of this image.
OK, so it’s not breath-takingly gorgeous; however, it is readable. Equally important, you don’t have to worry about parameters like –detailed; instead, you always get all the help that’s available for a topic (with no weird word breaks at the end of a line). And that’s not the half of it: help topics for all the other cmdlets (and for the About files) are never more than a click or two away; there’s full-text search; and you can access the information any time you want to, even if PowerShell isn’t running. (After all, this is just a .CHM file.) As an added bonus, we’ve even included the VBScript to Windows PowerShell Conversion Guide, just for the heck of it. All in all, that’s a pretty good deal.
Note. Don’t tell anyone we said this, but we’re not sure why you’d ever want to read help in the PowerShell console window rather than just read that same information in the graphical help file. After all, other than a minor edit or two the content is identical; it’s just easier to read in the graphical help file. Granted, you can’t just type a command similar to Get-Help Get-ChildItem and view that information in the graphical help file … or can you? Hmmm …. |
Needless to say, this is all available for free. Just click here to journey to the Microsoft Download Center and start the download. What you’ll end up with is a self-extracting .ZIP file that contains a single file: PowerShell.chm. Extract that file to the folder of your choice and then open the file (e.g., by double-clicking PowerShell.chm in Windows Explorer). At that point you can start clicking, searching, reading – and learning – to your heart’s content.
But I Like to Type!
Yes, we know: a lot of you were attracted to Windows PowerShell in the first place because you like working from the command prompt; you’d actually prefer to type Get-Help Get-ChildItem –detailed from the command prompt than to open up Windows Explorer, locate a .CHM file, open the file, and then search for the Get-ChildItem topic. Hey, that’s fine; the Scripting Guys have you covered as well.
As it turns out, it’s easy to configure Windows PowerShell so that you can open the graphical help file by typing a command very similar to Get-Help Get-ChildItem. You’ll have to do a little copying and pasting (and maybe a tiny bit of modification), but that’s a small price to pay for the capability we’re about to show you.
To begin with, you need to open your Windows PowerShell profile; you can do that simply by starting PowerShell and then typing the following command from the command prompt:
notepad $profile
Note. By default your profile is blank, at least until you add something to it. As a matter of fact, by default the file that holds your profile doesn’t even exist. This isn’t a problem in Windows XP. If you type the preceding command and your profile doesn’t exist yet you’ll see a message box asking if you want to create the file. Click Yes and you’ll have a blank profile open in Notepad. Things get a little more difficult in Windows Vista. If you type the preceding command before you’ve created a profile you’ll receive a message box that says “The system cannot find the path specified.” Your only choice is to click OK, at which point you’ll have a blank instance of Notepad open but no profile file. To find out where your profile should be, simply type this at the command prompt: $profile This will return something like this: C:\Users\kenmyer\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1 Simply save the Notepad file to this location (you might have to create the WindowsPowerShell folder), with this name (Microsoft.PowerShell_profile.ps1) and you’ll have your profile. At this point you can continue on with the rest of these instructions. |
When the file is open, copy the following function, paste it into your profile, and then save the profile:
function get-guihelp
{
if ($args[0].contains("about_"))
{$a = "HH.EXE mk:@MSITStore:c:\scripts\powershell.chm::/about/" + $args[0] + ".help.htm"
Invoke-Expression $a}
elseif ($args[0].contains("-"))
{$a = "HH.EXE mk:@MSITStore:c:\scripts\powershell.chm::/cmdlets/" + $args[0] + ".htm"
Invoke-Expression $a}
else
{if ($args[0].contains(" "))
{$b = $args[0] -replace(" ","")
$a = "HH.EXE mk:@MSITStore:c:\scripts\powershell.chm::/vbscript/" + $b + ".htm"
Invoke-Expression $a
}
else
{$b = $args[0]
$a = "HH.EXE mk:@MSITStore:c:\scripts\powershell.chm::/vbscript/" + $b + ".htm"
Invoke-Expression $a
}
$a
}
}
What have we done here? Well, this function (which we named Get-GUIHelp) enables you to access the graphical help file from the command prompt. Want to access help for the Get-ChildItem cmdlet? Then start up PowerShell and type the following at the command prompt:
Get-GUIHelp Get-ChildItem
Press ENTER and not only will the graphical help file open, but it will navigate to the Get-ChildItem help topic.
Note: You’ll probably need to close Windows PowerShell and reopen it again before you can start using this new cmdlet. That’s because Windows PowerShell reads in profiles when it opens, so anytime you change your profile you should close then reopen your PowerShell window. |
Prefer to view the About_Parsing topic instead? OK:
Get-GUIHelp About_Parsing
This is exactly the same kind of syntax you use to call up PowerShell’s built-in help engine; the only difference is that you type Get-GUIHelp rather than Get-Help. (And yes, tab expansion works as well.)
Heck, this even works with the VBScript to Windows PowerShell Conversion Guide. Suppose you’re familiar with the VBScript InStr command but aren’t sure how to perform the same task using Windows PowerShell. Well, then just ask GUI-Help for information about InStr:
Get-GUIHelp InStr
Keep in mind that some of the VBScript topics (like For Each) consist of two words. To access those topics from the command prompt you need to enclose the topic name in double quote marks, like so:
Get-GUIHelp "For Each"
If you aren’t sure what topics are available to you, just fire up PowerShell.chm and look at the table of contents. The names listed in the table of contents correspond quite nicely to the topic names.
Note. What if you make a mistake and type in the name of a topic that doesn’t exist (for example, you type Get-Comman rather than Get-Command)? No problem. The help file will still open; it’ll just display an error message as opposed to a topic page. |
We won’t bother to explain how this function works; if anyone is interested send an email toscripter@microsoft.com and we’ll consider doing an article on it in the future. For now we’ll just note that we stored our copy of PowerShell.chm in the C:\Scripts folder; that’s why you see the path c:\scripts\powershell.chm several times in the function code. Do you have to store PowerShell.chm in C:\Scripts? No; you can store the file anywhere you want. (Well, OK, maybe not up in the attic or under the bed. But you know what we mean.) However, if you do stash the file somewhere other than C:\Scripts you’ll need to modify the function so it points to the correct location. For example, suppose you put PowerShell.chm in the D:\My Scripts folder. In that case you need to modify the function so that any lines that reference the file path to the .CHM file look something like this:
{$a = "HH.EXE mk:@MSITStore:d:\my scripts\powershell.chm::/about/" + $args[0] + ".help.htm"
Invoke-Expression $a}
You get the idea.
OK, then what about this: Suppose you like the basic concept, but hate the idea of always having to use the command Get-GUIHelp. Is that going to be a problem? Nope. Don’t like the name Get-GUIHelp? Then give the function any name you want. For example, suppose you’d prefer to type something along the lines of gg Get-ChildItem. That’s fine; then just name your function gg:
function gg
Or, add the following command to your profile to create an alias named gg:
Set-Alias gg Get-GUIHelp
Either way you’ll be able to access the graphical help by typing in commands like this one:
gg Get-ChildItem
Not bad, if we do say so ourselves.
A Final Thought or Two
For the most part, and as we noted earlier, all we did here was reformat the help topics, add a few hyperlinks as we saw fit, and then jam everything into a .CHM file; we did no editing whatsoever (well, other than fix a spelling error if we happened to notice one). What that means is that (with the exception of the VBScript to Windows PowerShell Conversion Guide, which we tossed in as a bonus) the help topics in the graphical help file are exactly the same as the help topics you’ll see when using the Get-Help cmdlet.
Which is good; that way you can rest assured that the help topics will be consistent regardless of whether you use the graphical help file or the built-in Windows PowerShell help files. So don’t worry: there won’t be anything in the graphical help file that contradicts the official PowerShell help files. That’s because the two are pretty much the same thing.
Ah, good question: what should you do if you find a mistake in the graphical file help? If you find a mistake, either a big one or a small one, send an email to scripter@microsoft.com. We’ll fix the problems in the graphical help file and, if necessary, release an updated version. (We’ll also pass this information on to the Windows PowerShell team; it’s obviously up to them whether any of these mistakes warrant an updated release of the actual PowerShell help files.)
In addition, please let us know if there is other information you’d like to see added to the graphical help file. We have no plans to release a beefed-up version of this help file; on the other hand, we don’t have any plans not to release a beefed-up version. Instead we’ll bow to customer demand: if enough people want to see X, Y, or Z added to the file, well, then we’ll see what we can do about adding X, Y, or Z to an updated version of the file.
And sure, we suppose that it is a little unfair that PowerShell users get a help file like this and yet there’s nothing comparable for VBScript users. If you’re a VBScript user and you’d be interested in seeing a similar help file for VBScript (including the ability to call up specific topics from the command prompt), well, let us know. We’ll play that one by ear as well.