| Back to Contents List |
|
The latest version of these files is available online at http://www.jafsoft.com/doco/docindex.html
The program offers a number of diagnostic aids. These can be awkward to use, but if you want to get a better idea of what's going on these can sometimes help.
The various diagnostic options can be accessed via the menu option
Conversion Options -> Output policies -> File generation
The program can be made to generate listing files. A fragment is shown below.
56: 103 |1.2.4 Who is the author?
57: 1 |
58: 104 |1.2.4.1 John A Fotheringham
59: 1 |
60: |That's me that is. The program is wholly the responsibility
61: |Fotheringham, who maintains it in his spare time.
62: 1 |
63: 1 |
These show the source lines in truncated form. Each line is numbered, and markers show how the line has been analysed. In this case the line with "Who is the author?" has been allocated a line type of 103 ("header level 3") and is followed by a line of type 1 ("blank"). A complete list of line types and code is included at the end of the file.
Three files are generated; a ".lis1" file which is a listing from the Analysis pass, a ".lis" file which is a listing from the output pass and a ".stats" file which lists statistics collected during the analysis. Ignore this last file.
The ".lis1" and ".lis" files have similar format, but represent the file as analysed before and after the application of program policies. Thus more lines will be marked as headings in the ".lis1" file, but only those that "pass policy" - i.e. are in sequence and at the right indentation - will be marked as headings in the ".lis" file.
Understanding these files is a black art, but a quick look can sometimes help you understand how the program has interpreted particular lines that have gone wrong, and give you a clue as to which policies may be used to correct this behaviour.
The program will display messages during conversion. You can filter these messages (e.g. to suppress certain types) by using the Menu option
Settings -> Diagnostics
These messages can also be output to a .log file by using the options under
Conversion Options -> Output policies -> File generation
This log file will contain all messages, including those suppressed by filtering. In the Windows version you can also choose to save the messages displayed to file.
Looking through the .log file can sometimes reveal problems that the program has detected and reported.
The program operates in three passes.
- The first pass analyses the file, and sets various policies automatically (assuming these haven't previously been loaded from a policy file).
- The second pass calculates the output file structure,
- The third pass actually generates the output files.
You can use the options under Conversion Options to review the policies that have been set.
Alternatively you can save these policies to file, using the menu option
Conversion options -> Save policies to file
Selecting the "save all policies" option. Be careful not to overwrite any existing "incremental" file.
This file will list all policies used, which you may review... particularly looking for any analysis policies that seem to have been incorrectly set.
In the fullness of time an [Error Manual] will be produced. (see 1.7)
See "how does the program detect and analyse tables?" and other topics in the "Tables" section of this document.
 |
Converted from
a single text file by
AscToHTM © 1997-2003 John A Fotheringham |  |