Hello everyone, I’m glad to present another release of PS Cmdlet Help Editor! New version (3.0) brings big changes in it’s functionality. Key changes in this release:

• Introduced Start Page;
• Introduced PS Help project file which stores help content and other settings;
• Introduced basic BB-code support (in future, BB-code support will be enhanced);
• Introduced an ability to publish help content online via MetaWeblog API.

User interface

Let’s look at the editor when you start it:

When you start the editor, it won’t load module list as in previous versions. Start page provides common guidance about how to start your project. The following options are:

• Create new project. In this case, the editor will load module list and then there are two options: start blank project or import existing help file from XML file (which is a part of the PS module);
• Open existing project.

Ok, we decided to create new project and import existing help content from XML:

We will see familiar editor UI: command list on the left side and editor fields in the center. There are 7 tabs:

• General – manages general help information about the command, like synopsis, description, input and return types and notes (see above);
• Parameters – manages command parameters description

• Examples – manages command examples

• Related Links – manages related commands

• Support Information – manages PowerShell and operating system support/requirements for the command. Information from this tab is used only in HTML views. It is not included in the XML help file.

• Output – allows to generate various views of the command: XML, raw HTML and rendered HTML.

• Advanced – contains additional information about the command.

This tab is used only when command is intended to be published online. It contains online article title (which is the same as command name), article id and article URL (when it is published online). In addition, there are two textboxes, where you can put extra information, which will appear before and after help topic. Just put arbitrary HTML code in the corresponding field.

BB-code support

If you wish to publish your help online, it is likely that you may want some formatting capabilities, to select or colorize the text, or put HTML links. I decided to use a ready library from Codekicker.BBCode project. It really works greatly and much better than I could even imagine. Although, toolbar contains only four buttons, there are additional supported tags which you should type manually:

• B tag. Example: [b]bolded text[/b], output: bolded text
• I tag. Example: [i]italicized text[/i], output: italicized text
• U tag. Example: [u]underlined text[/u], output: underlined text
• S tag. Example: [s]stroked text[/s], output: stroked text
• color tag: Example: [color=red]colored text[/color], output: colored text
• url tag: Example: [url=http://www.microsoft.com]Microsoft[/url], output: Microsoft
• br tag: Example: [br], output: new line. This tag just converts [br] to <br /> HTML tag.

you can combine multiple tags, for example: [b][color=blue]blue bold text[/color][/b] will result: blue bold text. You can always verify how it will be rendered by generating HTML view in the Output tab.

In future I’m planning to add [code], [font], [size] and other (upon needs) tags. In the editor, you can select text block:

and click appropriate format button or use hotkeys.

Online publishing

Initially I developed editor for my own needs – to maintain help for my PowerShell PKI module. Currently there are about 100 commands and each release was a hell pain for me: generate html source, go to codeplex, click required article, click edit, reach the html source input in the RTB, paste HTML, edit appropriately and publish. STOP THIS MESS IMMEDIATELY!!! I explored available on internet solutions and started with MetaWeblog API implementation and usage. As a XML-RPC library I used XML-RPC .NET library and wrote my own interface implementations. So, how it works?

When the module is loaded, you can open Module Properties (from toolbar):

This dialog allows you to specify provider name (currently only CodePlex provider was tested), credential information, web site name and online fetching options. When you selected provider, provider URL (if you use custom provider) to a MetaWeblog API endpoint and credential data, click Connect button to get a list of web sites supported by the server. Select the site, and click Save to save these settings in the project (in order to save them into a file, you need to save the project).

Few words about the password. I tried as much as possible to securely work with passwords. At the runtime, the password is stored in the SecureString. Once you click Connect, password is cleared from password box and is stored in a secure object. When you click Save button, the password is encrypted by a DPAPI and is stored in an encrypted way in the file. Obviously, the password can be decrypted on the same computer only. Be aware about this.

In addition, there is “Fetch now” button, which allows to retrieve existing online help content. When you hit the button, it downloads posts from the server, finds articles that match commands in the module and saves related information, so when you publish command help online – you will edit existing article, instead of creating a duplicate. Of course, if there is no existing article, online publisher will create a new one.

There might be cases, when online page was deleted. In this case, when you update the page (cmdlet contains article ID information) an error is thrown and online data is removed from the command, so you will be able to create it again.

Other

Also, I started code rewrite, refactoring to prepare it for future enhancements. They are just plans, but who knows. For example, I want to implement tabbed projects, so you can work on multiple modules at the time, each module will reside in it’s own tab.

Since now, PS Cmdlet Help Editor is shipped in an MSI package. Just install and start to work. Thanks to Advanced Installer team again for MSI packager!

Feedback

This release is in RC (release candidate) stage. Although, I tested all required functionality, something may not work, work incorrectly or even crash the app at certain circumstances. Therefore, if you found a bug, inconsistency, you are welcome at: Discussions and Issue Tracker. In next few days I will update information on the project web site (as it is stale).

Hope, you will enjoy new editor!

---