First Looks

ComponentOne Doc-To-Help 7.5: Generate Help Documentation

Every program needs documentation of some type. Plus, first looks at GridEX Control for .NET, more.

• By Mark Collins-Cope
• 03/01/2005

Every program needs documentation of some type, and ComponentOne Doc-To-Help 7.5 can make it happen. Doc-To-Help is designed to generate help documentation from a Microsoft Word document in Microsoft HTML Help 1.x, JavaHelp, HTML 4.0, Microsoft Help 2.0, and printed manuals.

I installed Doc-To-Help easily on my Microsoft Office 2000 test platform. It integrates nicely with Office, and the toolbar is well organized, although it took me a while to remember the functionality associated with each icon. A wizard walks you through the process of setting up a project.

I created a new project and compiled an HTML file in no time. You can open the help file and search for information by typing your search criteria in the form of a question. Doc-To-Help creates an index behind the scene to handle the natural-language request. You can control some of the parameters of the search, such as how many items are returned or what confidence level must be met in order to be included in the search results. You can also disable natural-language searching if you don't want this feature.

Doc-To-Help lets you create modular help files. You can take several Doc-To-Help projects and create a master project or hub project used to create a parent/child relationship. This allows you to make changes to one section of your help without recompiling or regenerating the parts that haven't changed.

Documenter for .NET lets you generate MSDN-style documentation for your assemblies (see Figure 1). Doc-To-Help uses reflection to determine the member functions and types for each of your assemblies, so source code isn't required. You will have to add strongly typed assemblies to the GAC. You can also easily modify a Word file that Documenter for .NET produced. Your changes won't be overwritten if you need to regenerate the document, as long as you don't change the parts of the document that are generated automatically from the data in the assembly. Doc-To-Help also incorporates XML data that you can put into your source code as a comment. This lets you update your source code and documentation at the same time, saving you time and cutting down on mistakes due to outdated documentation.

Documenter for .NET lets you select how much information you want it to pull from the assemblies. If your base class is derived from a .NET class, I'd recommend unselecting it from the list of data to be processed. If you leave it selected, it will pull in all the data associated with the .NET Framework classes, which is well documented already.

Both developers and technical writers will appreciate Doc-To-Help. I would certainly recommend this product to facilitate documenting your project. The time it saves you is definitely worth it.

Doc-To-Help 7.5 Professional
Component One
Web: www.componentone.com
Phone: 800-858-2739; 412-681-4343
Price: $999.95
Quick Facts: Generates help documentation automatically in several formats from Microsoft Word documents.
Pros: Generates MSDN-style documentation of your .NET code; all major help formats are supported.
Cons: Learning curve required to take advantage of all the features offered; must add your strong-named assemblies to the GAC.

Web GridEX Control for .NET: Use Smart Web Grids
by Andy Clark

Janus Systems' Web GridEX Control for .NET is a fully functional, hierarchical grid control for ASP.NET projects that supports in-place editing. You can use it as a data-bound control with little required programming.

GridEX adds a grid to your application that you can bind to a data set and configure to display hierarchical data. Users can work through the hierarchy by clicking on the "+" sign to show detailed records or the "-" sign to hide them. Users can also resize columns, drag and drop to move columns, and control the grid's grouping. All of this requires no programming on your part beyond defining the grid and populating its data set.

GridEX provides a strong set of developer tools to support its functionality. It comes with its own designer, making it easy for you to select and format your grid's columns (see Figure 1). You can control the color and shading of the lines in your grids, and you have complete control over each column's coloring and font. You can also use editors to control how each column interacts with the user. GridEX provides editors for checkboxes, calendars, large text fields, drop-down lists, and many other types of data presentation. The designer allows you to define sort conditions, create filters, and add aggregate functions such as counts, sums, averages, and standard deviations to the grid. All this is available without requiring you to write a single line of code.

GridEX also offers strong runtime capabilities if you're prepared to do some coding. The control's interface supports a broad range of events, methods, and properties that allow you to control both the appearance and contents of the grid. This interface lets you change the shading of cells based upon their content, control all facets of the grid's appearance, and store the results of user edits back to your application's database.

GridEX comes with solid documentation and an excellent set of tutorials that showcase the control's capabilities while teaching you how to use it. Janus' support is extremely responsive, and I encountered no language difficulties working with this Panamanian corporation. Note that Janus does not usually offer phone support at this time.

Janus' GridEX is a fully functional, hierarchical grid control for Web applications. It provides an excellent interface for users who prefer a spreadsheet-oriented UI.

Janus Web GridEX Control for .NET
Janus Systems
Web: www.janusys.com
Phone: 011-507-6750805
Price: $389
Quick Facts: Hierarchical grid control for ASP.NET
Pros: Easy to use; supports inline editing; flexible.
Cons: None.

Use a Cross-Platform File Repository

Perforce SCM System 2004.2 helps you maintain a software configuration management (SCM) file repository and integrate that repository into your applications.

Perforce includes all the capabilities of a complete SCM tool. It lets you place source code in a central repository and track code changes (see Figure 1). You can lock source-code modules so that only one developer at a time can work with a file. It also allows multiple users to work on a file concurrently, and it provides tools that reconcile the different copies. Perforce tracks file versions, and it labels the versions that your software releases contain. You can group changes in order to identify the work done to correct a bug or implement a change.

Perforce has a particularly impressive set of reports for tracking changes over time. The Revision Graph report displays your file in a separate window and shows different versions as you move through the file history with a slider bar. However, this feature doesn't seem to work with filenames with embedded spaces such as "my code.cs."

Perforce also lets you define triggers that fire when files change. You can use triggers to run batch jobs that perform maintenance chores, a feature you can leverage to automate building and testing processes within your SCM.

You manage the Perforce repository through a server that must reside on a Unix, Mac OS, or Windows platform. Windows clients can work through a standalone Explorer-like client, a Web client, several IDEs (including Visual Studio and VS.NET), a command-line interface, or API calls. Note that Perforce integrates directly into Office, Visual Studio, and VS.NET environments. Perforce clients are also available for Unix, VMS, Linux, Macintosh, and other platforms, making Perforce ideal for cross-platform development teams.

This flexibility also offers you the intriguing possibility of using Perforce's file repository for more than SCM. The API interface gives you the option of integrating the Perforce repository into apps that work with collaborative documents. This type of repository might not work well with heavily formatted documents, such as word-processing or spreadsheet files, but it could give you a useful toolset for managing collaborative flat-text, HTML, and XML files.

The Perforce staff is prompt, helpful, and knowledgeable. The documentation is well written.

Perforce requires you to do a fair amount of planning and setup before it's functional. Your development group might need to give someone the job of administering the Perforce server and assisting in client configuration. Large staffs might require a full-time administrator. However, this is probably true of any SCM tool.

Perforce is a powerful tool for distributed development. The planning you must do to get the most out of it is well worth the effort, particularly for cross-platform development teams.

Perforce SCM System 2004.2
Perforce Software Inc.
Web: www.perforce.com
Phone: 510-864-7400
Price: Starts at $750 per user
Quick Facts: Flexible multiplatform software configuration management system.
Pros: Provides a file repository you can access through TCP/IP from a variety of clients. Features tools for viewing change history.
Cons: Requires extensive up-front planning and setup work.

Show Users Complex Data

Red Brook Software's WiredNav 2.0 is an excellent tool for displaying data based on complex relationships. It implements a control that examines the properties in your data-bound controls and synchronizes them—no coding is required.

The WiredNav control installs in the General section of your VS.Net toolbox. You add WiredNav to a form by dragging and dropping it. WiredNav adds a record browser to your application that is similar to the ADO Data control, but more powerful. It not only supports moving among records, but searching, printing, reporting, record insertion, editing, data validation, and commit/rollback as well. WiredNav implements these features through disconnected recordsets that minimize application impact on your database server (see Figure 1).

WiredNav can examine the data bindings within your other controls. For example, suppose you have a textbox showing an employee name, a grid showing employee sales, and another grid showing order status, all of which are populated using data adapters. WiredNav examines the data bindings to link these controls together. As the user goes through the list of employees using the WiredNav control, the sales and order grids update automatically. The user can also edit fields and save changes. Filling WiredNav's disconnected recordset is the only overhead required for these operations. The user can fill the disconnected recordset by using a button on the WiredNav control. You could also fill the recordset within your code—the only code you'll need to write to use WiredNav.

WiredNav is compatible with a number databases, including SQLDataAdapter, OleDbDataAdapter, OracleDataAdapter, ODBCDataAdapter, and BPDDataAdapter. It also works with Microsoft data-bound controls, the ComponentOne's FlexGrid and True DBGrid, Developer Express' XtraGrid, Infragistics' UltraGrid and WinGrid, Janus Systems' GridEX, and Xceed Grid. The reporting features work with Crystal Reports as well as reporting services.

Red Brook Software's support is prompt and knowledgeable. However, I was disappointed with WiredNav's documentation. The sample code is useful, but the reference documentation does not detail the control's API. Also, I'd prefer to see a walkthrough tutorial that shows you how to set up the control. Fortunately, WiredNav is easy to understand, and I had little trouble getting it to work.

WiredNav is helpful for applications that use complex forms with many data views. Disconnected recordsets can increase your application's scalability by reducing the database's workload, but you must be careful to make sure that the queries behind your data adapters are not so open-ended that they retrieve unnecessarily large amounts of data across your network. WiredNav is a great tool for rapid development. It is up to you to use it appropriately.

WiredNav 2.0
Red Brook Software
Web: www.redbrooksoftware.com
Phone: 518-248-3450
Price: $199
Quick Facts: Synchronizes data-driven controls on a form using disconnected recordsets.
Pros: Quick way to develop views of data with a wide variety of relationships.
Cons: Documentation needs some work.