Project Documenting Machine

Summary

PDM is a tool for an automated generation of a Visual FoxPro project documentation, or a documentation of Visual FoxPro files not linked to a project. PDM generates the output as an XHTML document. PDM documents project properties, databases (tables, views, relations, stored procedures), free tables, queries, visual libraries, forms, programs, fll libraries, reports, labels and menus. It is also able to document related projects without producing duplicities.
The whole configuration is stored in an INI file format.

Graphics user interface (GUI) - basic settings

The GUI is an extension of PDM, it is not necessary to use it to run PDM. From version 1.2.0 it is fully implemented as MDI and differs slightly from version 1.1.2. Even thought it looks like the form is overfilled with options, it actually contains just the most important options for the document generation. Each group of files (including the project, which is seen as a group of files as well) has its own page with its options. Further options are located on modal forms.

General page

On this page you can define the source (a project or free files), output (target) directory, if a generation should be interrupted after certain number of errors and which parts of the documentation should be generated. This group of checkboxes is disabled for free files and it is set automatically according to the file extensions. "Default path" defines the default project path, which can sometimes be different from the directory where the project is located and it influences the absolute path of files (don't ask me about details, please ask the users of VFX framework :).

PDM file creation, save, opening and run

In versions prior to 1.2.0 an empty PDM file is automatically opened, in new versions it must be created via "File->New" option. Next, you select a project or "One or more files" on the General page. Then the configuration needs to be saved via "File->Save". Now you can safely run the document generation (even if the generation crashes for whatever reason, the configuration is saved). After the generation is finished you are asked whether to preview it in the default web browser.

Basic settings of the generated XHTML document

The output XHTML document contains lots of lists and active components. The list can be ordered, the active components can be collapsed or expanded. For several types of the output (report and label details, menus) the width of the right column can be defined, for most of file groups you can define wheter to include source code and detail description.

Custom and GCT pages, Statistics option

The Custom and GCT pages are slightly "off-topic". In the Custom page you can define local and remote document references (via http, ftp protocols, etc.). You can describe the reference and define if it should be copied to repository. "GCT" (Global class tree) is a special page with a complete list of classes and their instances. The "Statistics" checkbox on the "General" page enables the generation of a simple statistics of number, types and size of the source files.

Other settings

On this page you can define global settings of the XHTML generation ...

Source code

Sometimes you need to generate documentation without a source code. There are 4 options available:
User
The inclusion or exclusion is set in the main module pages
Always Include
The source code will always be included
Always Exclude
The source code will always never be included
Only Signed
Only the source code with a special key in its comments will be included
You can also set the syntax coloring:
Project Documenting Machine 1.1.2
None
No syntax coloring
PDM
The syntax coloring is controlled by a record in the schemes table
VFP
The syntax coloring is generated according to the actual VFP IDE settings
User
The syntax coloring is defined by a user CSS file
Project Documenting Machine 1.2.0
None
No syntax coloring
Plugins
The syntax coloring is controlled by a special plugin
You can also define if lines should be numbered (Row Counter) and a left margin.

Description

This page controls the detail procedures/methods description. This description can be a part of the source code, it which case it is defined as a comment in the code and the Start and End documentation tag needs to be filled. If the description is inside #IF #ENDIF, the "Only comment" checkbox needs to be unchecked and the whole description must be wrapped by the start the end documentation tag (West Wind HTML Help Builder).

Other

On this page, there are other options, e.g. "Don't process excluded files", "Format HTML with spaces", "Format HTML with CRLF" etc. The default state of the active components is defined here:
User
The expansion/collapse is defined in the pages of the main module
Always collapse
The active components will always be collapsed
Always expand
The active components will always be expanded

Print

The page margins and an option to run the print process automatically after the generation is finished.

File list

Not all files are always suitable for documentation: some files can belong to a different project, sometimes some information needs to be hidden. This dialog is available only if the generation source is defined as a project and allows for the following options:
All files
All files will be processed (please be aware there is also the "Don't process excluded files" option)
All, except
All files will be processed, except those selected in the listbox on the right hand side
Selected files
Only the selected files will be processed

GUI - special settings

After you sober up from an euphoria, you will find out there are other things...

Plugins

Plug-ins serves for additional alteration of the HTML documentation generation. In the form, there is a selection box for selecting a plug-in group and a listbox with the corresponding plugins. Each plugin should have its own dialog with settings. Some plug-in groups are restricted in allowing only ine plug-in to be selected, e.g. only one plug-in can be selected in DIAMP, DIAP or DIAF groups.
At present, there are 8 plug-in groups:

DIAMP (Detail information about a method or a procedure)

Visual Foxpro PDM
My own specification of the comments syntax. It allows to combine plain text with XHTML, include an expression, a source code snipped or a reference to a class, method or a property
Visual Foxpro PDM (Metadata)
Another specification of my own. The information is stored as XML. It allows to combine plain text with XHTML, include an expression, a source code snipped or a reference to a class, method or a property. Sample files are stored in the test directory: diamp_pdm.prg a diamp_pdm.pdm.
Agnes's Methods and Procedures
Agnes's plug-in for the detail method and procedure description.
WW HTML Help Builder
This plug-in handles the documentation syntax defined in WW HTML Help Builder. To make this work properly, the "Only comment" checkbox in the "Description" page, and the whole block needs to be wrappend with the Start and End documentation tags. Sample files can be found in the test directory: diamp_wwhhb.prg a diamp_wwhhb.pdm.

DIAP (Detailed description about a property)

Visual Foxpro PDM
My specification. It allows entering of an expressions, a source code snipped or a reference to a class, method or a property.
Visual Foxpro PDM (Metadata)
My specification, entered as XHTML. It allows to enter an expressions, a source code snipped or a reference to a class, method or a property. Sample files can be found in the test directory: diamp_pdm.prg a diamp_pdm.pdm.
Agnes's property description plug-in
Agnes's plugin for the detailed property description generation.

DIAC (Detailed class description)

PDM - Detailed description of a class or an object
Sample plug-in.
Agnes's plug-in
Agnes's plug-in for detailed description generation.

DIAF (Detaled description of a file)

PDM - Detailed file description
Sample plug-in.
Agnes's file description
Agnes's plug-in for detailed file description.

EFRX (FRX Extension)

XFRX Extension
This plugin documents the control codes of the XFRX report engine.
MERE Extension
This plugin documents the control codes of the MERE report engine.
FRX2Word Extension
This plugin documents the control codes of the FRX2Word report engine.
FRX2Any Extension
This plugin documents the control codes of the FRX2Any report engine.
eReports Extension
This plugin documents the control codes of the eReports report engine.

PJXEX (Project properties extension)

Project properties - VFX
This plugin documents the additional properties of VFX framework projects.

AC (After creation)

Basic plug-in
The simplest plugin. It serves for the documentation generation alteration, to be exact, it can be used for finalization tasks, eg. file copy.

BC (Before creating)

Basic plug-in
The simplest plugin. It serves for the documentation generation alteration, to be exact, it can be used for source file preparation.

DCOP (Dynamic addition of a classes, objects or PEMs)

PDM - test
Sample plug-in.

CONV (Conversion of HTML to ...)

HTMLDOC
This plug-in creates a file for HTMLDOC utility, for conversion of the generated HTML to PDF
HTML Help Workshop
This plug-in creates a file for HTML Help WorkShop utility, for conversion of the generated HTML to CHM

Project overview

"Project overview" is a reference to a document, which contains the summary information about a project, something like a start page. If this document is simple (a file), it can be automatically copied to a repository.

User comments

There are three basic ways to define comments in VFP: NOTE, * and &&. In registry, there is also an "automatic comment", the default of which is *!*. Some programmers modify this default comment or use another sequence of characters (custom scripts). This dialog allows you to define the list of user comments types, which enables PDM to correctly process comments.

Friendly projects

If multiple project share files, in is not necessary to generate the documentation of these files for every VFP project. With the "List of files to process", it is possible to make the HTML documentation more effective.

If this list is defined, the references for all files, classes and prgs are generated (this can take some time) from the listed friently PDM projects and the main PDM project, and then the documentation for the mail PDM project is generated. The files that are not processed are being looked up in the generated references.

If a list of PDM projects is processed, then:


With this technique, the complete HTML documentation can be generated for not only a tree dependecies, but also cross dependencies.

a) Tree dependence
The framework project contains classes, that are used by independent projects a), or one-way dependent projects b).
a)	     FrameWork			b)	    FrameWork
	         |				    	|
    	         |					|
  	 -----------------			-----------------
  	 | 	   	 |		  	| 	 	|
         |		 | 			|		|
      Invoices         Stock		   Invoices <-------- Companies	
a) Cross reference
The framework projects contains classes, that are used by other projects, dependent on each other.
	     FrameWork		
	         |		
    	         |		
  	 -----------------	
  	 | 	   	 |	
         |		 | 	
      Stock <-----> Sale point

Setup and Cleanup

Some tables have indexes with external or internal functions, where the parameter can be, for example, a variable defined during the program execution. In this case, it is necessary to define such a variable before the generation (Setup) and release them after the generation (Cleanup). Please do not forget the "ADDITIVE" clause when setting up libraries or procedure files, this could release files used by PDM.

User settings

General

GUI
The location if the visual class with GUI definition (you can create your own GUI).
Language
The folder with a DBF table with localized strings definition. There are two tables, one for the PDM kernel, the other for the strings used for XHTML generation. The table with the localized GUI string is in a different location and used automatically.
Associate PDM file
A "good application attribute" is to ensure the files association on OS.
Repair registry/Clear registry
Sometimes you may need to repair or clear the registry
Loader
VFP IDE enables to load any application during the startup. This can be used for altering the default VFP menu and add options or external utilities. PDM from version 1.2.0 contains its own loader, which support this (all you need is to recompile) and it is unversal enough to support normal EXE modules as well.
Integrate with VFP IDE
This option will ensure that PDM will ask the loader for registration or unregistration.

Previewers

You can define more application in the previewers page. One of the applications as set as "default". This application will be invoked to show the generated XHTML document after the generation process finishes.
ID
Unique ID. It can be entered when a new application is being added
Title
The title of the application
File
The location of the application
Reset do Default
Clicking this button will set the application as the default previewer

Default Extension

This list should conver all files from FP 2.0 to VFP 9.0. It is recommended that you do not modify this list.

User's GUI

Only PDM menu
Sets if VFP IDE menu will be visible
Remember most open files
The number of files PDM remembers
Show MRU list
Show the "Most Recently Used" files
Show only files:
The number of files displayed in MRU
Show only windows:
The number of windows in the windows list.
Start browser
Start browser after generaton. The available options as "Always", "Ask" or "Never".

Command line

PDM can be run in a batch mode, without GUI.

Version 1.1.2

GUI is invoked if:

Running without GUI

1) DO PDM WITH "myproj.pjx","c:\temp\myproj", "myproj.pdm"
The settings are taken from myproj.pdm, but the myproj.pjx project is processed, sending the output to c:\temp\myproj directory.
2) DO PDM WITH "","", "myproj.pdm"
The settings are taken from myproj.pdm, including the project to generate and the output directory.
3) DO PDM WITH "myproj.pjx","c:\temp\myproj"
The myproj.pjx project is processed, sending the output to c:\temp\myproj directory, with default settings.
4) DO PDM WITH "","","x:\test\xxa000.pdm,x:\test\xxa001.pdm"
x:\test\xxa000.pdm and x:\test\xxa001.pdm PDM projects are processed. The first two parameters are ignored.
5) DO PDM WITH "program1.prg,forms1.scx","c:\temp\myfiles", "myfiles.pdm"
The settings are taken from myfiles.pdm, the program1.prg and forms1.scx files are processed, sending the output to c:\temp\myfiles directory.
6) DO PDM WITH "program1.prg,forms1.scx","c:\temp\myfiles", "myfiles.pdm", "",1
The settings are taken from myfiles.pdm, the program1.prg and forms1.scx files are processed, sending the output to c:\temp\myfiles directory. There will be a separate directory for each of the files.

Running with GUI - language mutations

The path is either relative to where PDM.APP is, or absolute.
1) Running GUI in English language: DO PDM WITH "","","","lang\en"
2) Running GUI in Czech language: DO PDM WITH "","","","lang\cs"
3) Running GUI in Slovak language: DO PDM WITH "","","","lang\sk"
4) Running GUI in Russian language: DO PDM WITH "","","","lang\ru"
5) Running GUI in Spanish language: DO PDM WITH "","","","lang\es"
6) Running GUI in French language: DO PDM WITH "","","","lang\fr"
7) Running GUI in German language: DO PDM WITH "","","","lang\de"

Version 1.20

Parameters list

files
The list of projects of files
--files"c:\temp\file2.prg,c:\temp x\file3.prg"
--filesc:\temp\file2.prg
--folder
The output folder
--folderc:\outfolder\
--folder"c:\out folder\"
--pdms
The location of PDM files
--pdmsc:\temp\test1.pdm,c:\temp\test2.pdm
--pdms"c:\temp\test1.pdm,c:\temp x\test2.pdm"
--lang
The folder with localization files
--langlang\fr\
--lang"c:\temp\pdm de\"
--severally
a flag, determining if the HTML documentation should be generated separately for a list of files
--severally1
--open
The PDM file that should be open after GUI is run
--openx:\test\tastrade.pdm
--open"x:\test pdm\tastrade.pdm"
--view
The PDM file, whose HTML output should be open
--viewx:\test\tastrade.pdm
--view"x:\test pdm\tastrade.pdm"
--print
The PDM file this HTML output of which should be printed
--printx:\test\tastrade.pdm
--print"x:\test pdm\tastrade.pdm"
--r
Fixes PDM registry records
--d
Removes PDM records from registry

Running without GUI

1) DO PDM WITH "--filesmyproj.pjx","--folderc:\temp\myproj", "--pdmsmyproj.pdm"
The settings are taken from myproj.pdm, but myproj.pfx will be generated to c:\temp\myproj directory.
2) DO PDM WITH "","", "--pdmsmyproj.pdm"
The settings are taken from myproj.pdm including source project and the output directory.
3) DO PDM WITH "--filesmyproj.pjx","--folderc:\temp\myproj"
myproj.pfx will be generated to c:\temp\myproj directory, with default settings
4) DO PDM WITH "--pdmsx:\test\xxa000.pdm,x:\test\xxa001.pdm"
The documentation will be generated for PDM projects x:\test\xxa000.pdm and x:\test\xxa001.pdm.
5) DO PDM WITH "--filesprogram1.prg,forms1.scx","--folderc:\temp\myfiles", "--pdmsmyfiles.pdm"
The settings are taken from myproj.pdm, but a documentation for program1.prg and forms1.scx will be generated to c:\temp\myfiles directory.
6) DO PDM WITH "--filesprogram1.prg,forms1.scx","--folderc:\temp\myfiles", "--pdmsmyfiles.pdm", '--severally1'
The settings are taken from myproj.pdm, but a documentation for program1.prg and forms1.scx will be generated to c:\temp\myfiles directory, with each file documentation being in a separate directory.

Running with GUI - Language mutations

The path is either relative to where PDM.APP is, or absolute.
1) Running GUI in English language: DO PDM WITH "--langlang\en"
2) Running GUI in Czech language: DO PDM WITH "--langlang\cs"
3) Running GUI in Slovak language: DO PDM WITH "--langlang\sk"
4) Running GUI in Russian language: DO PDM WITH "--langlang\ru"
5) Running GUI in Spanish language: DO PDM WITH "--langlang\es"
6) Running GUI in French language: DO PDM WITH "--langlang\fr"
7) Running GUI in German language: DO PDM WITH "--langlang\de"

Looking inside

PDM is implemented with a strict code and GUI separation. The PDM "kernel" code is all in PRG fiels, GUI is in visual classes. The settings are stored in INI files, separately for the code and GUI. Very little is stored in registry. And, there is the multilanguage support.

Configuration files

The main configuration file is stored in PDM root. It is synchronized with configuration files stored in user profile (both have the same structure). In the user profile (C:\Documents and Settings\%username%\Application Data\pdm), there are two files pdm.ini and gui.ini, which stores the GUI settings.

Alternative tools

Sometimes you need to see the content of the DBC container. The standard Visual FoxPro commands are not sufficient and PDM is too complicated for such a simple task. That's why you may consider using alternative utilities with specific focus.
bbdblist
Exports table structures and indexes from DBC to XLS (via OLE)
dbcdoc
Exports table structures, indexes, local and remote views (basic info)
disprine
Simple table referential integrity export to text file
DocScx
Exports forms to Microsoft Word document. It contains the list of objects, properties and methods contents.
DocVcx
Exports visual classes to Microsoft Word document. It contains the list of objects, properties and methods contents.
pttables
Prints table structures to the default printer
West Wind HTML Help Builder
A professional tool for CHM format documentation creation. It can import DBC container, visual classes or classes from PRG files. It can also import COM, TLB libraries and more.
dblist
Print the table structures to printer.
Export Form/Class to Word 97
Exports SCX/VCX to Word 97 documents.
Table structure for DIR/DBC
Exports tables, views and structures to HTML documents.
Listing of MENUs designed with the MENU Builder
A simple list of PADs and BARs from MNX files - a report.
Some utilities can generate complete documetation of a VFP project, but these are often commercial.
MakeDoc (free)
VFP project documetation generation.
RapidDoc
VFP project documentation generation do Microsoft Word.