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.
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.
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 :).
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.
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.
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.
On this page you can define global settings of the XHTML generation ...
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.
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).
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
The page margins and an option to run the print process automatically after the generation is finished.
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
After you sober up from an euphoria, you will find out there are other things...
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)
DIAP (Detail information about a property)
DIAC (Detail information about a class)
DIAF (Detail information about a file)
EFRX (FRX Extensions)
PJXEX (Project properties extensions)
AC (After Creation)
DCOP (Dynamic class, objects and PEMs addition)
CONV (Conversion of HTML to ...)
BC (Before Creation)
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" 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.
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.
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:
The PDM projects without friendly projects are processed first.
The list of references is generation for the rest of the PDM projects and their friendly projects.
This part can take quite some time, becuase the PRG files are analyzed where the class definitions are looked for.
The rest of the PDM projects is processed.
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
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.
PDM can be run in a batch mode, without GUI.
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.
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.
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.