Updates to PscxHelp

Topics: Developer Forum
Feb 22, 2007 at 8:39 AM
I changed this project to be a customized MSBUILD project. It builds about_pscx.help.txt and Pscx.dll-Help.xml every time you build the project now. So it will slow down builds somewhat but I think it is important that we start getting immediate feedback on the state of the documentation without waiting for the help guru to occassionally generate new docs and check them in.

I highly encourage you to start using the help so that you can see how many holes we have to fill in. We have a ways to get to the state we were at with the 1.0 release. :-( Of course, we do have lots of new functionality to document so I guess that's understandable and we are getting closer to have auto-generated help instead of manually generated help (at least with about_pscx.help.txt).
Feb 22, 2007 at 8:50 AM
BTW I had to modify the execution of the PowerShell scripts to remove the -NoProfile option because I need to query PSCX related functionality.
Feb 22, 2007 at 9:16 PM
Hey Keith, sounds great, but the help system has changed so much that I no longer know where or how to begin in order to create help for my provider (gac) and cmdlets (compression).

Any chance you could knock up a few paras either here or in a more permanent portion of the developer wiki ?
Feb 22, 2007 at 11:14 PM
Edited Feb 22, 2007 at 11:14 PM
I'm still trying to understand the area of cmdlets and provider help generation myself. It seems that Jachym wrote a New-HelpSkeleton.ps1 script that generates the skeleton info for each cmdlet in the snapin. The only problem is that because of the desire to support localized help we've most of the help text out of the cmdlets themselves into the XML file generated by this script. These are currently in PscxSnapin\Help. However once you start adding text to some of these XML files you can't really run this script again since you don't want to overwrite finished XML files and there's nothing to handle the fact that these files are checked in. What would be nice is create a similar script (or modify New-HelpSkeleton) so that you can specify the cmdlet that you want to generate help for. After that, it is a matter of:

1. Generating a skeleton XML file (could always copy another XML help file)
2. Fill in the skeleton with useful information about your cmdlet.
3. Check it into PscxSnapin\Help. All the XML help files are currently marked as Embedded Resource but I don't see why it shouldn't be none. It doesn't make sense to me to embed that much text into Pscx.dll especially since it won't be referenced??

Provider help is perhaps something we haven't worked out yet. Suggestion is that we create files in PscxSnapin\Help called something like GacProvider.xml. For an example of these should be formatted, take a look at: $pshome\en-us\System.Management.Automation.dll-Help.xml at line 3601. We will probably need to update the XSLT files to massage this info into the generated Pscx.dll-Help.xml file. Of course, it is entirely possible that Jachym has already thought this through and has another way to do this. We should wait to hear from him on Provider help.
Feb 26, 2007 at 4:40 PM
1, 3) I'm going to update the script to generate the output directly into the Help directory, and keep the existing files. It could update them with added parameters too (1.2). Perhaps we should move the xml files from the snapin project to the PscxHelp project? You're right, there's no need to have them compiled into the dll, I was just lazy.

I'd love to see something like the cmdlet help generator for providers, but can we make it for 1.1? There are things for which help could be generated semi-automatically, for example the dynamic parameters...
Feb 26, 2007 at 9:46 PM
I'm fine with punting on generation of provider help for 1.1. I think we could just rip the format for providers out of the PowerShell help file and fill that in minimally for our providers. Then check those files into the PscxHelp dir and make sure that the content gets merged into Pscx.dll-Help.xml.
Feb 27, 2007 at 12:54 AM
... I've actually got a PS Cmdlet that I've built (and Hanselman has been bugging me to post) that will read the XML comments and cmdlet attributes to create .dll-Help.xml files.
Feb 27, 2007 at 5:48 AM
Sounds cool. Jachym modified something I wrote for 1.0 to perform in a similar manner except that it doesn't deal with XML doc comments. It (Get-CmdletMaml) used attributes instead which unnecessariy weighed down the metadata. However he really wants to be able to support localized versions of the help file. Unfortunately it seems to require removal of many of the comments from the source which puts a burden on development of the english help files in return for the "potential" of having localized help files.

It's not that I'm against localized help files. I just want to get the basic english help in place first. :-) I wonder if your solution might be better for this at least in generating the english help entirely from attributes and the source code.
Feb 27, 2007 at 4:42 PM
If nothing else it would give a good starting point.

I've been trying to see if I could get the MAML schema that the help files are based on (or documentation). It would definately help in writing more automated documentation. Haven't found anything on the MSFT site.
Feb 27, 2007 at 6:17 PM
i really don't like keeping the looooooong lines of text in the attributes. if you guys see any benefit in keeping them in the source code, i'd prefer some xml comment on the top or something. the attributes are hard to read, edit, etc....
Feb 27, 2007 at 7:35 PM
Edited Feb 27, 2007 at 9:23 PM
I agree. My SnapIn uses XML comments for the bulk, so you have the XML Documentation file generated by the compile. The attributes are used for figuring out where they go in the documentation and the specific parameter attributes that show up in the documentation. I'll upload the source tonight so you can see my quick and dirty work that I've done.
Feb 28, 2007 at 10:25 AM
You can obtain TFS client here: