2.6.2 - Document Preparation - JdlDocument

John W. Campbell

2.6.2.1 Introduction

This class enables a specific type of document processing to produce documents of a consistent style primarily for the Web. The documents are processed from one of two sources:
  1. A simply structured document in format derived for use with this object, called pre-xhtml format.
  2. A marked up version of a Java source file.
The pre-xhtml format has a handful of XML type tags to define the title, author, introduction, sections and sub-sections. A subset of XHTML markup elements may be included within the text of these items if needed. The main advantage of using this simple additional structure is that the program will automatically number sections and sub-sections and generate links to these sections.

The markup for Java source files is compatible with the basic 'javadoc' markup. The JdlDocument methods enable the internal translation of this markup into pre-xhtml format and then into numbered and linked sections and sub-sections.

The JdlDocument object enables this process to be taken further to create a whole set of linked documents with a complete set of contents (with links). In this case back links to higher level documents in the set will be output automatically at the end of each document. An option exists to enable additional information, defined in a footer file, to be output at the end of each document if required.

Detailed descriptions of the markups required are given in the user documentation of the program DocExtractor which uses this JdlDocument object as its basis.

The output from the program will usually be an XHTML format file though there is also an option to produce a simple ascii text file.

Class, fields, constructor and methods:

Class Details
Accessible Fields
Constructor
Read documents
Write Document Files
Links list

2.6.2.2 Class Details

Package:
Jdl.JdlLib;
Class name:
JdlDocument
Class definition:
public class JdlDocument
Extends:
Object
Implements:
none
Actions:
none

2.6.2.3 Accessible Fields

The following accessible fields have been defined:

public final static int PXH
Input file type is pre-xhtml.
public final static int JAVA
Input file is a marked up Java source code file.
public final static int XHTML
Output is an XHTML format file.
public final static int TXT
Output format is as ASCII text file.

2.6.2.4 Constructor

2.6.2.4.1 Introduction

A single constructor is available.

Constructor:

Standard constructor

2.6.2.4.2 Standard constructor

Constructs an empty JdlDocument object

Constructor Definition:
public JdlDocument(boolean lst)
Parameters List:
lst
List context flag; if true, list the file names of documents as they are processed and a context string when an error is encountered (from 20 characters before to 40 characters after the character where the error was found) in the document source text, if false, do not.

2.6.2.5 Read documents

2.6.2.5.1 Introduction

This section has methods to read either a single document or a document set.

Methods:

Read document - readDocument
Read Document Files - readDocument
Read document set - readDocumentSet

2.6.2.5.2 Read document - readDocument

This method reads in a single document either from a pre-xhtml file or from a marked up Java source code file. This document will replace any existing document data currently stored. Note that the required processing of the input document depends on which type of output file will be required. Hence the output file type needs to be specified at this stage of the procedure, rather than when one of the writing methods is subsequently called.

Method Definition:
public boolean readDocument(String root, String fname, int out_type, JdlError jerr)
Parameters List:
root
The path of the directory in which the input file is to be found. May be specified as null if it is in the current directory.
fname
The name of the input file. If the file name extension is '.java' this will be assumed to be a Java source file. Otherwise a pre-xhtml format input file will be assumed (preferred extension '.pxh').
out_type
The output type as the constant 'XHTML' for an XHTML output file or 'TXT' for a plain text file.
jerr
This returns details of any error condition. If an error was found 'err.err' will be returned as true, errorr message(s) will be returned in 'err.msg1' (and 'err.msg2') and 'err.flag' will be set as follows:
= -1, Error opening input file
= 1, I/O Error
= 2, Error parsing data from a Java source file
= 3, Error parsing pre-xhtml data
Note that a value of 3 may be returned when parsing data from a Java source file as it is intitially processed into pre-xhtml data.
Method Return:
Returns true if the reading and processing of the input file was successful or false if there was an error (see 'jerr' above for details).

2.6.2.5.3 Read Document Files - readDocument

This method reads in a single document either from a pre-xhtml file or from a marked up Java source code file. This document will replace any existing document data currently stored. Note that the required processing of the input document depends on which type of output file will be required. Hence the output file type needs to be specified at this stage of the procedure, rather than when one of the writing methods is subsequently called.

Method Definition:
public boolean readDocument(BufferedReader bsr, int in_type, int out_type, JdlError jerr)
Parameters List:
bsr
A buffered reader created from the input file.
in_type
The input file type = 'PXH' for a pre-html file or 'JAVA' for a Java source file.
out_type
The output type as the constant 'XHTML' for an XHTML output file or 'TXT' for a plain text file.
jerr
This returns details of any error condition. If an error was found 'err.err' will be returned as true, errorr message(s) will be returned in 'err.msg1' (and 'err.msg2') and 'err.flag' will be set as follows:
= 1, I/O Error
= 2, Error parsing data from a Java source file
= 3, Error parsing pre-xhtml data
Note that a value of 3 may be returned when parsing data from a Java source file as it is intitially processed into pre-xhtml data.
Method Return:
Returns true if the reading and processing of the input file was successful or false if there was an error (see 'jerr' above for details).

2.6.2.5.4 Read document set - readDocumentSet

This method reads in a document set given the name of the parent document file. The input files will contain details of other files which form part of the document set. These file names for these linked files will be specified relative to the root directory specified as one of the parameters for this method. Note that the required processing of the input document set depends on which type of output file will be required. Hence the output file type needs to be specified at this stage of the procedure, rather than when one of the writing methods is subsequently called.

Method Definition:
public boolean readDocumentSet(String root, String fname, int out_type, JdlError jerr)
Parameters List:
root
The path of the directory relative to which the input files are to be found. May be specified as null if it is in the current directory.
fname
The name of the top level input file. If the file name extension is'.java' this will be assumed to be a Java source file. Otherwise a pre-xhtml format input file will be assumed (preferred extension '.pxh').
out_type
The output type as the constant 'XHTML' for an XHTML output file or 'TXT' for a plain text file.
jerr
This returns details of any error condition. If an error was found 'err.err' will be returned as true, errorr message(s) will be returned in 'err.msg1' (and 'err.msg2') and 'err.flag' will be set as follows:
= -1, Error opening the top level file
= 1, I/O Error reading the top level file
= 2, Error parsing data from a top level Java source file
= 3, Error parsing a top level pre-xhtml data
= 4, Error reading a file linked from a document section
= 5, Error reading a file linked from a document sub-section
Note that a value of 3 may be returned when parsing data from a Java source file as it is intitially processed into pre-xhtml data.
Method Return:
Returns true if the reading and processing of the input document set was successful or false if there was an error (see 'jerr' above for details).

2.6.2.6 Write Document Files

2.6.2.6.1 Introduction

This section contains methods to write a document set or an individual document. If required, a single document may also be selected from a document set with its section numbering being derived from its position within the document set. Note that the output file type (XHTML or TXT) will already have been set through a parameter to the document reading method which was used. Each method has a version which allows the specification of a footer file of XHTML commands to be output at the end of each document.

Methods:

Write document - writeDocument
Write document - writeDocument
Write document set - writeDocumentSet
Write document set - writeDocumentSet
Write selected document - writeSelectedDocument
Write selected document - writeSelectedDocument

2.6.2.6.2 Write document - writeDocument

This method outputs a file for the single document read in, or for the top level document if a document set was read. Any links to child documents will be ignored. Note that the output file type (XHTML or TXT) is as set via the preceding document reading method.

Method Definition:
public boolean writeDocument(String out_dir, String chapname, String secnum, boolean number, JdlError jerr)
Parameters List:
out_dir
The directory for the output file or the current directory if this is specified as blank or null.
chapname
The chapter name if required, otherwise blank or null. If this is given, a section number string should also be specified.
secnum
The section number string for the top level (title level) of this document, if required, otherwise blank or null.
number
If no section number string is given, then this must be set to false if no section numbering is required or true if section numbering is required. In the latter case sections will be numbered as 1, 2, 3 etc. and sub-sections as 1.1, 1.2, ... 2.1, 2.2 etc.
jerr
This returns details of any error condition. If an error was found 'err.err' will be returned as true, error message(s) will be returned in 'err.msg1' (and 'err.msg2') and 'err.flag' will be set as follows:
= 1, Error opening the output file
= 2, Error outputting the file
= 8, Error writing end of file
Method Return:
Returns true if the output was successful or false if there was an error (see 'jerr' above for details).

2.6.2.6.3 Write document - writeDocument

This method outputs a file for the single document read in, or for the top level document if a document set was read. Any links to child documents will be ignored. Note that the output file type (XHTML or TXT) is as set via the preceding document reading method.

Method Definition:
public boolean writeDocument(String out_dir, String chapname, String secnum, boolean number, String footer_file, JdlError jerr)
Parameters List:
out_dir
The directory for the output file or the current directory if this is specified as blank or null.
chapname
The chapter name if required, otherwise blank or null. If this is given, a section number string should also be specified.
secnum
The section number string for the top level (title level) of this document, if required, otherwise blank or null.
number
If no section number string is given, then this must be set to false if no section numbering is required or true if section numbering is required. In the latter case sections will be numbered as 1, 2, 3 etc. and subsections as 1.1, 1.2, ... 2.1, 2.2 etc.
footer_file
Name of footer file whose XHTML contents are to be added at the end of the document (within the document body).
jerr
This returns details of any error condition. If an error was found 'err.err' will be returned as true, error message(s) will be returned in 'err.msg1' (and 'err.msg2') and 'err.flag' will be set as follows:
= 1, Error opening the output file
= 2, Error outputting the file
= 8, Error writing end of file
= 9, Error reading or writing footer data
Method Return:
Returns true if the output was successful or false if there was an error (see 'jerr' above for details).

2.6.2.6.4 Write document set - writeDocumentSet

This method outputs the files for a document set. Note that the output files type (XHTML or TXT) is as set via the preceding document set reading method.

Method Definition:
public boolean writeDocumentSet(String out_dir, String chapname, String secnum, boolean contents, JdlError jerr)
Parameters List:
out_dir
The directory for the output files or the current directory if this is specified as blank or null.
chapname
The chapter name if required for the top level document, otherwise blank or null. If this is given, a section number string should also be specified.
secnum
The section number string for the top level document, if required, otherwise blank or null.
contents
If true a set of contents will be written at the end of the top level document, if false no contents will be written.
jerr
This returns details of any error condition. If an error was found 'err.err' will be returned as true, error message(s) will be returned in 'err.msg1' (and 'err.msg2') and 'err.flag' will be set as follows:
= 1, Error opening the top level output file
= 2, Error outputting the top level file
= 4, Error writing document linked from a section
= 5, Error writing document linked from a sub-section
= 6, Error writing contents
= 7, Error writing back_links
= 8, Error writing end of file
Method Return:
Returns true if the output was successful or false if there was an error (see 'jerr' above for details).

2.6.2.6.5 Write document set - writeDocumentSet

This method outputs the files for a document set. Note that the output files type (XHTML or TXT) is as set via the preceding document set reading method.

Method Definition:
public boolean writeDocumentSet(String out_dir, String chapname, String secnum, boolean contents, String footer_file, JdlError jerr)
Parameters List:
out_dir
The directory for the output files or the current directory if this is specified as blank or null.
chapname
The chapter name if required for the top level document, otherwise blank or null. If this is given, a section number string should also be specified.
secnum
The section number string for the top level document if required, otherwise blank or null.
contents
If true a set of contents will be written at the end (except for any footer) of the top level document, if false no contents will be written.
footer_file
Name of footer file whose XHTML contents are to be added at the end of each document (within the document body).
jerr
This returns details of any error condition. If an error was found 'err.err' will be returned as true, error message(s) will be returned in 'err.msg1' (and 'err.msg2') and 'err.flag' will be set as follows:
= 1, Error opening the top level output file
= 2, Error outputting the top level file
= 4, Error writing document linked from a section
= 5, Error writing document linked from a sub-section
= 6, Error writing contents
= 7, Error writing back_links
= 8, Error writing end of file
= 9, Error reading or writing footer data
Method Return:
Returns true if the output was successful or false if there was an error (see 'jerr' above for details).

2.6.2.6.6 Write selected document - writeSelectedDocument

This method outputs a file for a single document which is part of a document set. The document sections/sub-sections will be numbered as determined by its position within the structure of the document set. Any links to child documents will be ignored. Note that the output file type (XHTML or TXT) is as set via the preceding document set reading method.

Method Definition:
public boolean writeSelectedDocument(String sel_source, String out_dir, String chapname, String secnum, JdlError jerr)
Parameters List:
sel_source
The name of the selected input file to be written.
out_dir
The directory for the output file or the current directory if this is specified as blank or null.
chapname
The chapter name if required for the document, otherwise blank or null. If this is given, a section number string should also be specified.
secnum
The section number string for the top level (title level) of this document if required, otherwise blank or null.
jerr
This returns details of any error condition. If an error was found 'err.err' will be returned as true, error message(s) will be returned in 'err.msg1' (and 'err.msg2') and 'err.flag' will be set as follows:
= 4, Error writing document if linked from a section
= 5, Error writing document if linked from a sub-section
= 8, Error writing end of file
Method Return:
Returns true if the output was successful or false if there was an error (see 'jerr' above for details).

2.6.2.6.7 Write selected document - writeSelectedDocument

This method outputs a file for a single document which is part of a document set. The document sections/sub-sections will be numbered as determined by its position within the structure of the document set. Any links to child documents will be ignored. Note that the output file type (XHTML or TXT) is as set via the preceding document set reading method.

Method Definition:
public boolean writeSelectedDocument(String sel_source, String out_dir, String chapname, String secnum, String footer_file, JdlError jerr)
Parameters List:
sel_source
The name of the selected input file to be written.
out_dir
The directory for the output file or the current directory if this is specified as blank or null.
chapname
The chapter name if required for the top level document, otherwise blank or null. If this is given, a section number string should also be specified.
secnum
The section number string for the top level (title level) of this document if required, otherwise blank or null.
footer_file
Name of footer file whose XHTML contents are to be added at the end of the document (within the document body).
jerr
This returns details of any error condition. If an error was found 'err.err' will be returned as true, error message(s) will be returned in 'err.msg1' (and 'err.msg2') and 'err.flag' will be set as follows:
= 4, Error writing the document if linked from a section
= 5, Error writing the document if linked from a sub-section
= 8, Error writing end of file
= 9, Error reading or writing footer data
Method Return:
Returns true if the output was successful or false if there was an error (see 'jerr' above for details).

2.6.2.7 Links list

2.6.2.7.1 Introduction

This has a single method for reading a file of data (pairs of link names and link file names) for resolving external named links.

Method:

Read links list - readLinkFile

2.6.2.7.2 Read links list - readLinkFile

This method reads a file containing pairs of link names and link file names for resolving external named links. These link names are given in the special <.link> tagged data with a link name.

Method Definition:
public boolean readLinkFile(String root, String linkfil, JdlError jerr)
Parameters List:
root
The path of the directory in which the input file is to be found. May be specified as null if it is in the current directory.
linkfil
The name of the file containing the link name/link filename data.
jerr
This returns details of any error condition. If an error was found 'err.err' will be returned as true, errorr message(s) will be returned in 'err.msg1' (and 'err.msg2') and 'err.flag' will be set as follows:
= -1, Error opening input file
= 1, I/O Error
= 2, Error in the file data

⇑ Up 2   ⇑ Up 1   ⇑ Top of this