Documentation + Globalization + Get-CmdletMaml

Topics: Developer Forum
Developer
Dec 20, 2006 at 12:15 PM
I was thinking how we could make writing the documentation easier. You see, now there are lot of places which need to be updated manually:

  • Cmdlet metadata
  • about_Pscx.txt
  • Readme.rtf
  • codeplex wiki

You mentioned you'd modify the Get-CmdletMaml to read an external MAML file with notes and examples. I guess we could take this further. I imagine a xml file which would contain all the localizable strings that are now in the HelpMessages (PowerShell does not use that anywhere, right?) and DescriptionAttributes, plus the samples, notes, and revision changes. For example:

<Command Name="Pscx.Commands.SendSmtpMailCommand">
....<Description>Sends email via specified SMTP server to specified recipients.</Description>
....<DetailedDescription>
........Sends email via specified SMTP server to specified recipients. This
........cmdlet checks for existence of several preferences that can make this cmdlet
........much easier to use. Those preference variables are:
..........* $PscxSmtpHostPreference="smtp.some.domain.com"
..........* $PscxSmtpPortPreference=587
..........* $PscxSmtpFromPreference="john_doe@some.domain.com"
....</DetailedDescription>

....<Parameters>
........<Parameter Name="SmtpHost">
............<Description>Specifies which SMTP host to use to send the email.</Description>
............<DefaultValue>Value of $PscxSmtpHostPreference if defined, otherwise null.</DefaultValue>
........</Parameter>
....</Parameters>

....<Examples>
........<Example Title="Without Preference Variables">
............<Code>
................Send-SmtpMail -SmtpHost smtp.domain.com -To jane_doe@some.domain.com `
....................-From john_doe@some.domain.com -Subject "Hi there " `
....................-Credential (get-credential) -Body @"
................>> Hi Jane,
................>> Let's do lunch.
................>> --
................>> John"
................>> "@
................>>
............</Code>
........</Example>

........<Example Title="Using Preference Variables">
............<Code>
................Send-SmtpMail -To jane_doe@some.domain.com -Subject "Hi there"
..............................-Body "Let's do lunch. --John"
............</Code>
........</Example>
....</Examples>

....<Revisions>
........<Introduced Version="1.0" />
........<Changed Version="1.1">New documentation</Changed>
....</Revisions>
</Command>

Get-CmdletMaml would combine this data with the non-localized metadata and produce the MAML file. There would be also another command (probably only a simple XSLT), which would transform all these files into the about_Pscx.txt or the WhatsNew-style document. We could also generate the wiki home page this way (or a whole wiki/html version of the MAML documentation, why not? I'd bet an accessible, simple, online manual would only increase Pscx attractivity for a casual site visitor). It could also include scripts documentation in the future...

Any suggestions?

PS. If the HelpMessages are, in fact, used somehow by the PowerShell runtime, (or they would start being used in a next version), we can always transform the cmdlet-xmls into a resx, and refer to the resources in code.
Developer
Dec 20, 2006 at 12:17 PM
crap, if i knew the forums support the wiki syntax, i'd format the xml correctly. sorry
Coordinator
Dec 21, 2006 at 12:43 PM
Yeah I've been thinking along these lines. Get-CmdletMaml could morph into Get-CmdletSyntaxMaml since that is the primary value it adds. That is unless we want to have Get-CmdletMaml do the merge between the auto-generated syntax and this separate file?
Developer
Dec 22, 2006 at 2:05 PM
I was thinking it would be a two-stage process: the first stage would merge the hand-made, per-cmdlet, localized xml with the data obtained from .net metadata. It wouldn't produce the MAML directly, but the xml would have a very similar structure (eg. it would contain the parameter sets, it would be all in a single file).
The second stage would simply transform the first stage output into the MAML, about_Pscx or a rtf/wiki change log.
Coordinator
Dec 24, 2006 at 7:08 PM
Is there a way we can generate all the parameter help from reflection on the cmdlets? First, most of the rest of the info comes from reflection. Second parameters are the most likely to change as we tweak cmdlets. Remembering to update the XML files will be problematic. We already have the AcceptsWildcardAttribute class. What other do we need? We can use the HelpMessage attribute to get the help text for each parameter.
Developer
Dec 24, 2006 at 9:03 PM
i would prefer not to keep the localizable text in code. first, it is too long and disturbs when reading the sources, second, it should really be in the resources, third, once we have all the examples and other content, it will be really uncomfortable to keep it as a multiline string parameter of an attribute.

you have to remember to add a help message either way, and you will see in the resulting maml you forgot something. i guess there isnt much of a difference then
Coordinator
Dec 24, 2006 at 9:35 PM
OK, let's put in the localizable file.
Developer
Dec 26, 2006 at 1:44 AM
and where should the files go? i put a few of them in the Commands directory, but i guess making a separate Help directory with the same structure as the Commands directory (so we can find them easily by type name), would be better....
Coordinator
Dec 26, 2006 at 7:31 AM
Dunno. One the one hand, having the doc files beside each source code file serves as a reminder to update the xml file if you changet the source. OTOH it would clutter up the source a good bit. So I could go either way but I guess I lean towards putting them in a separate dir like "Docs" or "Help" or something like that. I think perhaps a flat list is OK for these help files. I don't see a benefit to mimicking the Pscx project's directory structure since the namespace a cmdlet is in has no bearing on the help.
Developer
Dec 28, 2006 at 2:31 PM
Is there some docu how and where to write the help for the cmdlet. I would like to add examples and maybe notes to the help of my cmdlets.
Coordinator
Dec 28, 2006 at 5:13 PM
Jachym has been busy working on this. I'm not sure if he is done with that piece just yet so hang tight for a bit until this gets sorted out.
Developer
Dec 28, 2006 at 5:43 PM
yeah, still working on it. i have support for notes in the Get-PSSnapinHelp, i am going to check it in once i update the maml.xslt.

you should probably still use the Description, DetailedDescription, Parameter(HelpMessage) and so on, so when we decide to move to the xml files, we can easily generate them from .net metadata.
Coordinator
Dec 30, 2006 at 6:37 PM
OK why do we have Messages.resx and Shared.resx? I'm not sure we care whether a message is shared or not, do we? Also what was wrong with just using the built-in (via Project Properties) string table?