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:
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:
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:
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.
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:
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.
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.
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!
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!
Post your comment: