by Ross Mack - GUI Computing
For a while there VideoSoft seemed to be content to stick with the two or three products they produced and not be in a hurry to do much more than the occasional new version. Well, those times have changed. In recent months we have seen the release of VSReports, VSData, and the latest VSDOCX. We have come to expect good things from VideoSoft based upon their excellent VSVBX and VSView products and they have not failed to live up to that expectation with this newest tool.
So, what is VSDOCX? Simply put, it's an intelligent tool that helps you document ActiveX controls (OCXs) and the way it does that is quite smart. VSDOCX offers two types of output: RTF, suitable for importing into Word or your favourite word processor and printing off as your printed manual, or neatly compiled help files.
After creating a new VSDOCX project you just add however many controls you wish to the project, simply by selecting the OCX files. VSDOCX then uses the OLE interfaces to those controls to interrogate what properties, methods, and events are exposed. From this information it builds the framework of a help file. It will happily deal with a number of OCXs being added to the one project, and with any number of controls in each OCX. For example, if you create a new project and add VSView.OCX and VSOCX.OCX to it, you will have a total of 7 controls documented. 4 in VSView, and 3 in VSOCX. To upgrade your VSDOCX project to a new version of a control simply add the new version over the old and VSDOCX will automatically update the documentation to include new properties, methods, and events and to discard redundant ones.
Of course, 16 and 32 bit OCXs are both supported. It also doesn't matter what the OCX was produced with (VC++, Delphi, VB5) as VSDOCX interrogates the OCX directly to get the required information, you don't even need the source code.
So, exactly how much of the work for creating the documentation for each event, method and property does VSDOCX do for you? Quite a lot actually. It prepares a topic for each property, method and event. It then specifies the type of the property, or type returned by the method. It intelligently generates an example of the correct syntax showing optional arguments, parameter names, and so on all correctly formatted.
For properties, you can even have VSDOCX attempt to figure out what the default value of the property is. It does this by actually generating an instance of the control and querying the property. Very cool, however it's not immediately obvious how you do this. What you need to do is right click on the Default Value field and select 'Paste Default Text' from the context menu. You can actually use this feature in the 'remarks' section for each property or method as well. In this case it generates an outline of what you need to say based on the parameters expected by the method or passed by the event. This may not go as far as writing the documentation for you, but it comes closer than anything I have seen and it really does give you a good starting point.
That's really what VSDOCX is all about, doing all the boring, tedious parts of documentation creation and leaving you to simply write the descriptive text (like: 'setting this property to 7 will cause your monitor to explode').
Speaking of writing the descriptive text, all the text you enter into VSDOCX can be formatted, as you would expect with bold, italic and underlining. Unfortunately, this is again only available through keystrokes or context menus and is therefore not immediately obvious. Jumps and popups can also be inserted in the same way, VSDOCX helpfully pops up a simply, unobtrusive dialog to let you select the destination topic. Cross-references can also be added very easily. VSDOCX defines two types, 'See Also' for related topics and 'Examples' for, well, examples. Adding either type of reference is simply a matter of selecting the desired topics from a list box.
You can also format your text using a normal proportional font or a fixed width font useful for code examples and such. Exactly what these fonts are is determined using a Styles tab which allows you to set all the general formatting options in one centralised place for your whole project. This means you have a little less control on a topic by topic basis, but does encourage a consistent look and this approach is certainly appropriate for the sort of documentation that VSDOCX is designed to help you produce.
One drawback with the styles screen is that to adjust a style you click on the area that demonstrates the style and adjust its properties from there, however it's not really obvious what different things are available to be formatted. Perhaps an accompanying list of formattable objects and a highlight in the display area would have been of assistance here. However, this is a minor gripe as I found after a little clicking that the screen operated pretty much as I expected. Perhaps the interface is more intuitive than I give it credit for.
You are probably getting the impression around this time that VSDOCX is quite rigid and not very flexible about how it does things. Well, yes it is. However, it is designed for a fairly specific task and the things it controls or produces automatically you probably will not want to change anyway. After all, it does a pretty good job of that stuff. In other areas it provides a reasonable amount of flexibility.
For example you can add additional topics to your help file that do not directly relate to properties, events, methods or controls. These can contain whatever you wish and can be referenced from wherever else in the project you like. The documentation even suggests some useful things you might want to consider putting in such topics, like 'How to contact Tech Support', 'Company Information' or a Registration form for your controls. Again, the problem I had here was applying formatting. The formatting options are perhaps a little lean for these sorts of topics and are only available via the context menu and keystrokes.
Perhaps I'm just too used to having formatting toolbars, but it seems that the ability to open up a full sized window with a complete formatting toolbar for working on this content would be helpful.
The other feature of VSDOCX that is worth mentioning is the layout tab that allows you to very simply change the order of the sections in your documentation and to select any sections that you want to not be included in the RTF and/or Help file output. This is only configurable down to the control level and not to the topic level, but I think that's more than adequate.
All in all the interface to VSDOCX is quite intuitive after a short play and works very effectively when you get down to real work. You will also find that the documentation is well put together as most VideoSoft documentation is (you would hope so for a documentation product). In fact I found the Quick Start provided in the help file and the demonstration OCX (including VB5 source) to be an excellent starting point and demonstrated just enough to get me started. From there you can quickly master this simple yet effective product.
An interesting note is that VSDOCX uses JET 3.5 to store each project in what are in reality JET databases with a .DCX filename extension instead of .MDB. In fact, the whole product turns out (after a little snooping) to be written with VB5 and makes extensive use of VideoSoft's own tools (VSOCX and VSFlex prominently). In fact the whole interface is largely a mass of VSElastics, a VSIndexTab, a VSFlexArray and some MS RichTextBoxes. I guess the fact that VideoSoft managed to produce such an excellent product using almost exclusively their owncontrols is a good self-advertisement.
If you are in the business of building OCXs or are part of a development team using that wants to effectively leverage the ActiveX control creation abilities of your tool (VB5, Delphi, VC++ or whatever) you need to take a serious look at what is really an excellent product. In fact, it's almost hard to believe it's a version 1.0.