John W. Campbell
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:
- A simply structured document in format derived for use with this
object, called pre-xhtml format.
- 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
- Package:
- Jdl.JdlLib;
- Class name:
- JdlDocument
- Class definition:
- public class JdlDocument
- Extends:
- Object
- Implements:
- none
- Actions:
- none
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.
A single constructor is available.
Constructor:
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.
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
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).
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).
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).
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
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).
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).
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).
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).
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).
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).
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
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