Vista - new cmdlet help editor problems

Hi all,

If anyone else is having problems using the latest version of the
cmdlet help editor -- e.g. getting error about missing
AspenCmdletManagement snapin -- just navigate to the install directory
and run installutil.exe against AspenCmdlets.dll to register the snap-
in. I guess Wassim forgot to add that step to his installer.

http://blogs.msdn.com/powershell/arc...itor-tool.aspx

I presume if you're writing cmdlet help files, you know where to find
installutil.exe ;-)

- Oisin

Oisin Grehan wrote:It's funny you make that assumption because that's totally not what I was
attempting to do (altho I do know about installutil.)

I was researching the best way to solve some documentation problems as I saw it
for scripts, not cmdlets. Some of us were talking about this on #Powershell the
other day. I want to have some sort of autodoc facility for my scripts. Here
are some requirements I've considered:

- simple to use
- easy to embed within a script
- at least some nod towards existing formats, if not outright compatability

Now what I've found about MAML, the XML schema which is used with cmdlet help
files, is this:
- XML schema isn't public (yet?)
- Number of tools to assist in its use can be counted on one finger

It's no harder to use than any other XML schema, but I don't see the point in
working in a strict doctype if I can't validate it. Also, an .XSLT would be
nice. I know these things exist inside Microsoft, not sure what their plan is.

Anyway, Powershell's lack of block comments means I may be a bit premature in my
autodoc plans unfortunately. I mean, it can be done with here-strings but
that seems a bit hacky.

--

Hal Rottenberg
blog: http://halr9000.com
powershell category:
http://halr9000.com/article/category...ng/powershell/

"Hal Rottenberg" <hal@xxxxxx> wrote in message
news:#wUY5Qv7HHA.3900@xxxxxxAs an ad-hoc convention, we adopted to following triple # comment style on
PSCX to allow for the automatic extraction of triple # comments into our
about_PSCX.help.txt help topic e.g.:

### <Script>
### <Author>Joris van Lier and Keith Hill</Author>
### <Description>
### Gets the possible alternate views for the specified object.
### </Description>
### <Usage>
### Get-ViewDefinition
### Get-ViewDefinition System.Diagnostics.Process
### Get-ViewDefinition Pscx.Commands.HashInfo $pscxhome\formatdata\*.ps1xml
### Get-Process | Select -first 1 | Get-ViewDefinition | ft
Name,Style -groupby SelectedBy
### </Usage>
### </Script>

results in this automatically getting put in the about topic:

Get-ViewDefinition
Gets the possible alternate views for the specified object.

Usage:
Get-ViewDefinition
Get-ViewDefinition System.Diagnostics.Process
Get-ViewDefinition Pscx.Commands.HashInfo
$pscxhome\formatdata\*.ps1xml
Get-Process | Select -first 1 | Get-ViewDefinition | ft
Name,Style -groupby SelectedBy

--
Keith

Keith Hill wrote:Sounds good to me. Ad-hoc is the best I could hope for since Microsoft is
playing MAML so close to the vest for some reason. (Not that you can directly
embed XML into PS1 files anyway.)
So did you guys document how you've done this? Is the parser in Powershell or
in managed code?

Have you thought about changing the elements names to be closer to MAML? e.g.
### <command:command>
### <command:name>Get-ViewDefinition</command:name>
### <command:description>
### Gets the possible alternate views for the specified object.
### </command:description>
### </command:command>

(Not a perfect translation, just a quick example.) OTOH, MAML is pretty ugly, I
retract the previous paragraph.




--

Hal Rottenberg
blog: http://halr9000.com
powershell category:
http://halr9000.com/article/category...ng/powershell/

"Hal Rottenberg" <hal@xxxxxx> wrote in message
news:#5PiSZx7HHA.5360@xxxxxxWe use a PoSh script that is checked into the source:

http://www.codeplex.com/PowerShellCX...ngeSetId=25826

--
Keith