A fledgling FAQ for JafSoft text conversion utilities

The latest version of these files is available online at http://www.jafsoft.com/doco/docindex.html

Previous page Back to Contents List Next page

5.0 Diagnosing problems for yourself

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

5.1 Generate a .lis file

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  | 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.

5.2 Generate a .log file

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.

5.3 Generate a .pol file

The program operates in three passes.

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.

5.4 Understanding error messages

In the fullness of time an [Error Manual] will be produced. (see 1.7)

5.5 Diagnosing table problems

See "how does the program detect and analyse tables?" and other topics in the "Tables" section of this document.

Previous page Back to Contents List Next page

Valid HTML 4.0! Converted from a single text file by AscToHTM
© 1997-2003 John A Fotheringham
Converted by AscToHTM