Database Schema Documentation

Time2HELP 1.0 supports a simple way of documenting database tables. The support is very basic in the 1.0 version, supporting simple (but effective) descriptions of tables and their columns. In the future, more extensive support for database schema documentation is planned.

Time2HELP keeps documentation of database schemas in DLDatabaseSchemaDoc XML files (hereafter called dbDoc files). This is very similar to the concept of UnitDocs. A single such file can contain documentation of multiple tables, but all tables are assumed to be in the same database "schema". (If you aren't used to the term 'database schema', just think of it as a set of tables "belonging together", e.g. the set (or an "interesting" subset) of tables in an MS Access database, in a directory containing Paradox/dBase/DBISAM tables etc.) Technically, all tables should be available via a single database connection of some sort.

Using Drivers
Time2HELP has a set of database "drivers" for extracting table and column info from a database, similar to how T2H extracts info from Delphi source code files. These drivers are used for automatically synchronizing database info with a dbDoc file, containing your documentation of a set of tables. See also installing database drivers
Note
You should not manually edit what is within the <AutoProperties> sections, as the contents of these will be refetched via the driver on the next synchronization.
T2H 1.0 will provide drivers for:

In addition, we will provide a "semi-manual" driver, in case you use a database not supported by T2H, but of which you are able to code a script building an "empty" dbDoc file for your database. Making this info available to T2H via the "semi-manual" driver enables T2H to synchronize your dbDoc file with this info.

Manually Entering Table and Column Names
If we do not support a driver for your favorite database engine, you may enter table and column names by hand.

A given schema may be documented in multiple DLDatabaseSchemaDoc files, ie the total doc for the schema may be a "union" of multiple DLDatabaseSchemaDoc files. If you use multiple files to document a single schema, you should take care to ensure that the summary and description for the schema itself is located in only one of these files (it doesn't matter which, T2H looks after it in all the files, but if present in multiple files, T2H will pick an arbitrary one).

Schema Name, Identifier etc
When adding a new database schema documentation file to a project, you define an (internal) name for it. This should be unique within the project. This name is only used internally in the project file, it won't show up in the help.

Schema Name
You also define a Schema Name for it, which may show up in the help. Time2HELP allows splitting the doc for a single schema into multiple files, therefore the schema name may not be unique within a T2H project.

Schema Identifier
In order for T2H to cope with the situation that the same help file may contain documentation for multiple tables having the same name (but within different schemas), a schema identifier is encoded in the topic id's (and HTML file names in HTML output) for the tables. Since schema names may contain characters not allow as topic ids, an extra Schema Identifier is needed. You typically should use as Schema Identifier the Schema Name with all spaces, special characters etc. stripped.

(Quite often you can use the same name for all the three values.

Documentation File
Here you specify either an existing DLDatabaseSchemaDoc file, or where you want it to be created. This file contains (or will contain) the doc for (some of) the tables in the given schema. We recommend using .dbDoc as the extension.

Time2HELP's Processing of DLDatabaseSchemaDoc Files

  1. All DLDatabaseSchemaDoc files in the project are loaded.
  2. The tables are grouped according to Schema Identifier.
  3. One .topics file for each group is generated, via a template file.
  4. Each .topics file is translated into WinHelp RTF or HTML etc "as usual".


HTML generated by Time2HELP
http://www.time2help.com