FlexDoc/XML - Running Generator

  1. Launching Generator from Command Line
  2. Generator GUI
  3. Multi-valued (List) Parameters
  4. Error Reporting
  5. Tips

1. Launching Generator from Command Line

To start the FlexDoc/XML Generator, use the following command (applicable with Java 9 or later):
java [java_options] --module-path <module_path> --module flexdoc.xml/xyz.flexdoc.xml.Generator [options] [XML files]
where all arguments are explained in this table:

Command/Arg Explanation
java A system command used to invoke JVM (Java Virtual Machine).

On Windows, that command may be as simple as 'java' (when you have installed Java properly). Alternatively, may look like:

"C:\Program Files\Java\jdk-17\bin\java"

Just don't forget to enclose it in double quotes, when the pathname contains spaces!

[java_options] The JVM options.

When you process large quantities of data (e.g. big XML files or lots of them), use -Xmx option to set the maximum heap size allocated by JVM. Otherwise, the generator may slow down and even run out of memory!

For example, setting -Xmx512m will allocate 512 Mb for the heap, which is OK for most purposes (e.g. to run XSDDoc) on 32-bit Java.

For 64-bit Java (running on 64-bit OS), we recommend to double the amount of allocated memory since lots of internal things (like memory pointers) get doubled in size on 64-bit (as compared to 32-bit OS).

So, on Windows 10 64-bit you should specify -Xmx1024m, instead of -Xmx512m. (For instance, allocating 512 Mb for 64-bit Java heap size is no longer enough to document big XML schemas using XSDDoc).

<module_path> Specify FlexDoc/XML module path.
Modules is a feature of modular Java that appeared since Java 9. Now, besides classes and packages, a Java application is broken also into modules. Module is a top-tier structure, which was introduced for better control of class dependencies, better encapsulation and the possibility of building custom JREs (which may include things not provided in the standard JDK).

Each module has a separate name and is typically packed as a separate jar-file (whose name is not necessary the same as the module name). The module path is the list of those module jar-files (their pathnames) and/or directories where they are found.

On Windows, the FlexDoc/XML module path looks as follows:

"%FDH%\lib\flexdoc-xml.jar;%FDH%\lib\xercesImpl.jar"

where
  • '%FDH%' must expand to the pathname of FlexDoc/XML home directory (e.g. C:\flexdoc-xml)
  • flexdoc-xml.jar is FlexDoc/XML main module file
  • xercesImpl.jar is Apache Xerces2 Java library

Notes:
FlexDoc/XML main module name The name of the Java module, which the generator class belongs to: flexdoc.xml

In modular Java, the application main class cannot be invoked just by its qualified name. The name of its module must also be specified.

generator class The qualified name of the FlexDoc/XML generator main Java class: xyz.flexdoc.xml.Generator
[options] Generator command-line options, which provide settings to control both the generator and the template application.
In fact, to run a big template application (like XSDDoc), lots of special settings may be needed. The generator resolves each setting as follows:
  1. First, it looks whether a setting was specified directly with an option on the command line.
  2. If it wasn't, the generator finds the generator.config file and looks for that setting in it.
  3. If the setting is not found still, its default value will be used.
That mechanism allows you to greatly optimize your Java command line (or your Ant/Maven build file, respectively).

Instead of specifying every single setting separately using command-line options, you may simply prepare everything you need at once using the generator GUI and, then, pass the result generator.config file with just one -config option on the command-line.

The generator GUI stores all settings, which you edit with it, in the generator.config file found in

{flexdoc-xml}/config
directory. (Actually, that location is not static. By default, it is specified in the flexdoc.config found near flexdoc-xml.jar. But again, it may be overridden with -config option, when you run the generator with GUI).

Having prepared all the necessary setting using the generator GUI, you may specify the result generator.config on the command-line with -config option, e.g.:

-config {flexdoc-xml}/config/generator.config
That will reduce most of your command-line options to just one!

You may prepare different generator.config files for different types of documentation, which will allow you to quickly setup the generator for a new kind of job just by specifying another config-file. That's what the generator GUI is for!

[XML files] One or many input XML files to process. They should be specified with separate command-line arguments, which may be either: Notes:
  • Multiple file specifications must be separated with spaces.
  • When a file specification contains spaces itself, it must be enclosed in double quotes.
  • When XML catalogs are used (see -xmlcatalog option), each XML file URL will be resolved by those catalogs. This allows you, for instance, to redirect some external file locations to their local copies on your system.

Command Line Options

The FlexDoc/XML Generator recognizes the following command line options:
-config
-d
-defaultcatalog
-flexdocconfig
-errlog
-f 		-format
-launchviewer
-license
-m
-nodialog
-o 		-p
-quiet
-template
-xmlcatalog
-xmltype
Please note that options not specified directly on the command line, first, will be searched in the generator.config file and only when not found their default values will be used.

Here are the option details grouped by category:

Template Options

-template <file>
Specifies the main template file to be executed by the generator. All what is generated is controlled by this template. The main template may call from itself another templates (subtemplates) producing either a single output file or multiple files (framed documentation).

The template file may be specified both with absolute or relative pathname. The relative pathname will be treated against the default template directory (specified in flexdoc.config file).

Examples:
-template C:\flexdoc-xml\samples\sales\sales.tpl
-template SingleDoc.tpl
-p:<parameter>=<value>

or

-p:<parameter> <value>
Specifies the value of a template parameter.
Notes:
  • You can find the necessary parameter names in the Template Parameter Inspector invoked from the Generator Dialog.
  • The boolean values should be specified as "true" and "false" strings (for example: -p:includeImages=true).
  • There are also enum parameters, which are strings limited to only fixed number of values. You can see all possible values accepted by an enum parameter in Parameter Inspector.
  • Now FlexDoc.XYZ supports multivalued (list) parameters, which can be equally specified on the command line using this option. See Specifying List Parameter on Command Line for more details.
  • When the value contains spaces, enclose it in double quotes (for example: -p:title="My Docs").
  • The first variant of this option allows you to specify the parameter with a single command line argument, the second variant breaks the option into two arguments (one for the parameter name, another one for the parameter value). This may be useful when you prepare some build files (e.g. for Ant/Maven).

Output Options

-format <HTML | RTF | TXT>
Specifies the output format. By default, HTML.
-o:<option>=<value>

or

-o:<option> <value>
Specifies the output format option.
Notes:
  • You can find the necessary option names in the Format Option Inspector invoked from the Generator Dialog.
  • The values of the boolean options should be specified as "true" and "false" strings (for example: -o:rtf.storeGraphicsInRTF=false).
  • The first variant of this option allows you to specify everything with a single command line argument, the second variant breaks the option into two arguments (one for the option name, another one for the value). This may be useful when you prepare some build files (e.g. for Ant/Maven).
-d <directory>
Specifies the destination directory for the generated report/documentation. This option works in conjunction with the -f option.

The output files are distributed in the following way:

  • In the case of a single-file output
    1. The output document is placed in the destination directory under default file name 'template_name.format_extention' (for example, in the RTF output format, template SingleDoc.tpl will produce document 'SingleDoc.rtf'). The -f option may override this name.
    2. All associated files (such as images, if not included in the document) are placed in the 'docname_files' subdirectory near the main document.
  • In the case of a framed multiple-file documentation
    1. By default, all generated files and subdirectories are placed in the specified destination directory. The frameset file produced by the main template is saved under the name 'index.html'.
    2. If a different name 'docname' is specified with the -f option, the frameset file is saved under this name. All other files and the subdirectory tree are moved into 'docname_files' subdirectory near the frameset file.

      This makes the whole documentation to look as to consist of only two file entities, which may be easier to distribute yet during the generation, especially when different types of documentation are produced from the same project.

Examples:
-template SingleDoc.tpl -format RTF -d c:\out
generate the document file c:\out\SingleDoc.rtf with the associated files subdirectory c:\out\XMLDoc_files\ (if any)
-template SalesReport.tpl -format HTML -d c:\out -f MySales
generate the report file c:\out\MySales.html with the associated files subdirectory c:\out\MySales_files\ (if any)
-template XMLDocFrames.tpl -format HTML -d c:\out
generate the framed documentation located in the directory c:\out\ with the main file index.html
-template XMLDocFrames.tpl -format HTML -d c:\out -f MyXML
generate the framed documentation with the main file c:\out\MyXML.html and all other files located in the directory c:\out\MyXML_files\
-f <file>
Specifies the output file name. This option works in conjunction with the -d option and specifies the name of the main output file (the one associated with the main template).

Typically, it should be used to specify a pure name associated with the generated report/documentation (for example, 'MySales'). However, the pathname may also be used. In that case, it is interpreted against the initial destination directory (specified with the -d option) and may override it. If the pathname is the absolute one, the -d option is effectively ignored.

-launchviewer[=<true | false>]
Tells the generator to execute a specific non-Java command to launch an external application able to view the generated result (for instance, an Internet browser for viewing HTML files or MS Word for RTF document).

Precisely, this command is specified in flexdoc.config file found near flexdoc-xml.jar file in the lib directory.

Examples:
-launchviewer
Do launch viewer
-launchviewer=false
Do not launch viewer, no matter what's specified in the generator.config

Processing Options

-xmlcatalog <file | URI>
Specifies an XML catalog file. The option argument may one of the following:
  • Local file pathname
  • URL
  • An abstract URI 'urn:flexdoc-xyz:xml:defaultcatalog', which denotes the default XML catalog
To specify multiple XML catalogs, use this option several times for each file.

All XML catalogs will be loaded before the data-source XML files and further used to resolve (or redirect) both the initially specified XML file URIs and any external identifiers or URI references found the actual XML files being processed.

For more details, please see: Installation / Configuration Files | XML catalogs.

Notes:

  • Besides the command-line option, XML catalogs can be equally assigned using generator GUI; see Generator GUI | Assigning XML Catalog(s).
  • When one or more -xmlcatalog options are specified on the command line, they will override the XML catalog settings stored in the generator.config. If you need to ensure that no XML catalogs (of those left from the previous GUI settings) will be used, just specify this option with the empty string argument: -xmlcatalog ""
  • When multiple XML catalogs are used, the order in which they are specified (on the command line or in the GUI) may be important! The same URI may have different resolutions according to different catalogs, but the one will be used, which was found in the catalog specified the first.
-nodialog[=<true | false>]
Do not invoke the Generator Dialog.

If this option specified, the generation will be started immediately according to the setting provided on the command line and in the generator.config (see -config option). Then, the generator exits.

-quiet[=<true | false>]
Suppresses displaying most of the status messages to Java console.
-errlog <file>
Specifies the error log file used when the FlexDoc/XML Generator is executed without the Generator Dialog (i.e. when -nodialog option is also specified on the command line).

By default, when an unexpected error/exception occurs during the generation and no GUI is enabled, all details about the error are printed to the standard console.

Using this option, you can assign a separate error log file, into which the detailed ERROR REPORT is dumped each time an error happens. Only brief messages will get on the console in that case. (See also Error Reporting for more details.)

The error log file should be specified as an absolute or relative file pathname. When the pathname points to a directory, it will be extended with the default “FlexDocXYZ.log” name (for example, setting "-errlog ." will be interpreted as 'FlexDocXYZ.log' file located in the current directory).

If the error log file does not exist, it is created in the event of error. Otherwise, the ERROR REPORT is appended to the existing file. In the case of any I/O error related to the error log file itself, everything will be printed to the console (along with additional the log file error message).

Configuration Options

-config <file>
Specifies the generator configuration file, which may contain options written manually or using the Generator Dialog. All generator options not provided directly on the generator command line are searched in this file.

If this option is not provided, the location of the generator config file will be searched in flexdoc.config which, by default, points to the file: {flexdoc-xml}/config/generator.config

-flexdocconfig <file>
Specifies an alternative path to the FlexDoc/XML main configuration file. By default, this file is 'flexdoc.config' which is searched in the directory where the FlexDoc Java library file 'flexdoc-xml.jar' is located. If not found, flexdoc.config is created automatically with default settings.
-license <files>
Specifies the locations of one or many license files.

The option value may include multiple file pathnames, which should be separated with the OS-specific path-separator character (e.g. ';' under MS Windows or ':' under Linux). Alternatively, you can specify different license files with any number of -license options on the command line.

The license files directly specified on the command line with the -license options will be loaded (and used) before any other license files:

This means that when you have placed several licenses for the same product in various files/locations (where the licenses are searched) and one license specified on the command line using -license option, that one will be used.

See also Multiple Licenses.

-m:<macro>=<value>

or

-m:<macro> <value>
Specifies the value of a macro, which can be used in flexdoc.config and XML Type Configuration files to allow configuring them from the command line.

Notes:

  • When the macro value contains spaces, enclose it in double quotes (for example: -m:LIBPATH="C:\Program Files\...").
  • The first variant of this option allows you to specify the macro with a single command line argument, the second variant breaks the option into two arguments (one for the macro name, another one for the macro value). This may be useful when you prepare some build files (e.g. for Ant/Maven).
-xmltype <files>  or  -xmlconfig <files>
Specifies the locations of one or many XML Type Configuration Files.

The option value may include multiple file pathnames, which should be separated with the OS-specific path-separator character (e.g. ';' under MS Windows or ':' under Linux). Alternatively, you can specify different config files with any number of -xmltype options on the command line.

All XML Type Configuration Files specified with the -xmltype options are loaded in addition to those assigned statically in the flexdoc.config. However, when an XML Type happens to be defined simultaneously in several files, the definition contained in a file directly specified on the command line will be used the first.

-defaultcatalog <file | URL>
Specify the location of the default XML catalog file. The option argument may be both the local file pathname and a URL.

For more details, please see: Installation / Configuration Files | XML Catalogs | Default XML Catalog

Command Line Argument Files

To shorten/simplify list of arguments on the command line, you can specify one or more files containing all those arguments you need. Any such file should contain space- or newline-separated arguments or options written the same way as on the command line.

When FlexDoc parses the command line arguments and encounters an argument beginning with the character '@', it treats the characters following it as a file name and expands the contents of that file into the argument list.

Example:

This will run FlexDoc/XML (on MS Windows platform):
set classpath=lib\xml-apis.jar;lib\xercesImpl.jar;lib\resolver.jar;lib\flexdoc-xml.jar
java -cp %classpath% xyz.flexdoc.xml.Generator @argfile
The argfile may contain the following lines:
-template templates/XMLDoc/SingleDoc.tpl
-p:title="Sales XML Files"
-format RTF
-nodialog
-launchviewer
samples/sales/sales.xsd
samples/sales/sales.xml

2. Generator GUI

Besides the command line options, FlexDoc/XML provides a different more user-friendly way for specifying most of the settings used by the generator.

When the generator starts without -nodialog option set on the command line, by default, it invokes the Generator Dialog, as shown on the following screenshot:

In this dialog, you can specify most of the settings needed for the generator as well as to start generation and track its progress.

The Generator Dialog can also be invoked from the Template Designer. In that case, the dialog fields are initialized from the default generator.config and the “Template” field is set to the current template open in the designer.

When the generator is started directly from the Java command line (e.g. by running generator.bat) and no -nodialog option specified, the Generator Dialog is launched automatically. In that case, the dialog fields are initialized with exactly those settings prepared for the generator – that is the generator options specified on the command line plus everything else loaded from the generator.config (see also -config option).

Specifying Template

In the “Template” field, you should specify the pathname of the main template to be interpreted by the generator.

The combo-box contains the list of the last used templates which allows you to quickly pick one when needed. When the Generator Dialog is invoked from the Template Designer, the “Template” field is preset to the current designed template.

This field duplicate -template option specified on the generator command line.

Setting Template Parameters

For the specified template, the “Params” button invokes the Template Parameter Inspector, like the one shown on this screenshot:

The inspector content is constructed dynamically from the parameter definitions contained in the given template. In fact, when you click the “Params” button, the template file is loaded and parsed in order to obtain those definitions. The parameter values are displayed and edited according to their types.

The bottom panel in the inspector dialog displays the description of the selected parameter (which is also obtained from the template). The first line of the description (the highlighted text) shows the internal parameter name. Use this name in the -p option to specify the parameter value on the generator command line.

See also: Multi-valued (List) Parameters | Specifying List Value in Parameter Inspector.

Choosing XML File(s)

In the “XML File(s)” field, you should specify one or many input XML files to process (i.e. used as the generator data source).

Each file specification must be either:

Multiple files specifications must be separated with spaces. When a file specification contains spaces itself, it must be enclosed in double quotes. For example, the following line specifies three XML files:
test1.xml c:\projects\test2.xml "c:\My Projects\test3.xml"

Assigning XML Catalog(s)

When you click the “Catalog” button, the following dialog will appear:

Here, you can add one or more XML Catalog files, which may be both local file pathnames and absolute URLs. The “Include default XML catalog” check-box allows you to add also the default XML catalog.

All specified XML catalogs will be loaded before the data-source XML files and further used to resolve (or redirect) both the initially specified XML file URIs and any external identifiers or URI references found within the XML files being processed.

For more details, please see: Installation / Configuration Files | XML catalogs.

Notes:

Selecting Output Format

In the “Output format” combo-box you can select the output format of the generated documentation. Currently, the following formats are supported: Since all document templates are output format independent, if you have specified one in the “Template” field, you can freely use any output format. The frameset templates are supported only by HTML output format.

Similar to the template parameters, the “Options” button near the “Output format” combo-box invokes the Format Option Inspector which is specific for the selected output format.

The bottom panel in the inspector dialog displays the description of the selected option. The first line of the description (the highlighted text) shows the internal option name. This name should be used in the -o option to specify the format option value on the generator command line.

The following screenshots show the option inspectors for each supported output format:

HTML Option Inspector

RTF Option Inspector

TXT Option Inspector

Specifying Output Location

Output folder
Use this field to specify the destination directory for the generated documentation. See -d option for more details.
Output file
Use this field to specify the documentation main output file name. See -f option for more details.

Starting Generation

Once all settings prepared, the generator can be started by clicking the “Run” button. Then, the dialog transforms and the progress panel appears:

The progress bar tracks the generation progress and shows the name of the output file being currently generated. The “Cancel” button stops the generation at any moment.

Once the generation has finished or cancelled, the Generator Dialog transforms back to the initial state. Then, the new settings can be entered and the generation started again.

When the generation was successful and the “Launch Viewer” check-box selected, the generator will try to launch an external application (e.g. MS Word) to view the produced result. See -launchviewer option for more details about this setting.

Generation Phases

FlexDoc generates the whole documentation in two phases: estimation phase and generation phase.

In the estimation phase, the generator quickly passes over all the source data and partially interprets the involved templates. During that, it collects the names and location of all documentation files to be created and all possible hypertarget locations within them. It also makes an estimation of the total generation time in order to graduate the progress bar.

During the estimation phase, only the message "Scanning data source, please wait..." is displayed on the generator dialog's progress bar. Please note, the estimation phase may take some time! On a lot of data (plus a slow computer), it may last some minutes. This does not mean, the generator hangs. Please wait!

During the generation phase, all template components are being fully interpreted and the real output generated. The progress bar is alive and shows what's being generated at the particular moment.

3. Multi-valued (List) Parameters

Since the version 1.7.2, FlexDoc/XML supports multi-valued template parameters (which we shall call also list parameters, for short).

List parameters allow you to pass to the template the whole vector of different values associated with the same parameter name. This provides a universal mechanism of implementing the user control over how the set of templates processes a certain type of data (or situations) that may come in unlimited number of variations.

The parameter inspector represents the whole value of a list parameter as a concatenation of all value items (represented as strings) delimited with a separator character. However, there is no need to process that string representation within a template. Rather, it will be parsed automatically by the Generator (as well as the parameter inspector ensures its integrity).

Specifying List Value in Parameter Inspector

In Parameter Inspector dialog, the entite list parameter value is displayed as a single string in the value field of the inspector row, where you can edit it as well:

Additionally, the list value can be edited as a multi-line text in a special dialog (invoked by the ellipsis button):

At that, when the allowed value item separators include newline, all currently used separators will be replaced with it so as to show each value item on a different line. When the editing in this dialog is finished, all newline-separators will be automatically replaced with another available separator suitable for single-line representation.

You can see all available value item separator characters in the “Parameter Description” window, when the list parameter is selected:

The separators are specified in the template along with the parameter definition.

Using Escapes

When the characters recognized as value item separators may also appear within the value items themselves, the list parameter may be defined so as to recognize escapes. In that case, each separator character can be equally used within value items if escaped with a backslash. For example, given that ';' is a separator, the following value item:
red;green;blue
can be specified like this:
red\;green\;blue
If a backslash is not consumed by an escape it will be remained in the text as is. To make sure that a backslash is not part of some escape, you may add another backslash. A sequence of two backslashes ("\\") is an escape itself, which represents a single backslash. This is important because backslashes may be used also in a secondary system of escapes within value items, which is specific to the given parameter.

When the escapes are recognized, the sequence "\n" is reserved to encode a newline character. The encoding of newline may be needed, for instance, when it is used not as a value item separator, but rather within multi-line content of value items themselves. In that case, the "\n" escape allows flattening the entire list value into a single line. This may be particularly important for specifying the list parameter on the command line (see also below).

Some list parameters can be specified to ignore escapes. This may be needed when backslashes must be frequently used within value items. (For example, the parameter will accept a list of Windows file pathnames.)

All possible escapes related to specifying of the value of a list parameter as a whole can be found in the “Parameter Description” window.

Specifying List Parameter on Command Line

To specify a list parameter on Javadoc command-line you should encode the entire list value into a single string (using the value item separators and possibly escapes) and provide that string as a -p option argument.

For example, suppose you need to pass into a template the list parameter 'gen.doc.element.names' with three value items:

link
target
key
You can do this using a single command line option (given that ';' is a value item separator):
-p:gen.doc.element.names "link;target;key"
(The quotes are necessary only when the parameter value contains spaces and must be treated as a single command-line argument.)

Alternatively, you can pass the same list value using multiple -p options, each one for a separate value item. e.g.:

-p:gen.doc.element.names link -p:gen.doc.element.names target -p:gen.doc.element.names key
You can even combine the two approaches simultaneously:
-p:gen.doc.element.names link;target -p:gen.doc.element.names key
Multiple options specifying the same list parameter can be mixed with other options on command line. However, the order in which the parameter options follow is important, because it defines the ordering of the list value items received by the template.

4. Error Reporting

Both FlexDoc/XML Generator and Template Designer may encounter various unexpected error situations. During the generation, the unexpected errors and exceptions may arise because of the following reasons:
  1. I/O errors (e.g. invalid file pathnames, disk full, etc.)
  2. Template errors/bugs (when something is wrongly specified in templates).
  3. Data source exceptions (in the case of FlexDoc/XML, these are exceptions thrown by the Apache Xerces2).
  4. FlexDoc core exceptions (may be caused by bugs not discovered and fixed yet).
FlexDoc tries to catch all such errors/exceptions and report about them along with the full diagnostics possible (i.e. where exactly and how the error has happened).

When the Generator Dialog is enabled, any error is reported via the error message dialog, like the one shown on the screenshot:

The error dialog shows brief information about the error. When more details are available, a full ERROR REPORT is created and dumped to the system clipboard. You can easily extract it (e.g. under MS Windows, just run Notepad and press Ctrl+V).

When the generator is executed without the GUI (-nodialog option is specified on the generator command line), by default, all exception/error details will be sent to the standard console. However, using -errlog option, you can specify a separate error log file. In that case, the ERROR REPORT will be dumped in that file; only brief messages will get on the console.
The detailed ERROR REPORT includes: Here is how an ERROR REPORT looks (the template line numbers and context elements are highlighted with special colors): 
===================================================================================
FLEXDOC.XYZ ERROR REPORT, 2016-11-23 18:13:21
===================================================================================
FlexDoc/XML, Version 1.10
Main class: xyz.flexdoc.xml.Generator
java.version=1.8.0
java.vendor=Oracle Corporation
sun.arch.data.model=64
os.name=Windows 7
os.arch=amd64
os.version=6.1
locale=en_US
-----------------------------------------------------------------------------------
GENERATOR INFO
-----------------------------------------------------------------------------------
Template Application: XSDDoc Error Demo
Main Template: C:\test\XSDDoc\FramedDoc.tpl
Loaded XML Files (2):
	http://www.w3.org/2001/XMLSchema.xsd
	http://www.w3.org/2001/xml.xsd
Output Format: HTML
Output Folder: C:\test\out\
-----------------------------------------------------------------------------------
ERROR DETAIL
-----------------------------------------------------------------------------------
Generator Exception:
No element map found with id 'all-element-usage'
-----------------------------------------------------------------------------------
When executing function call 'findElementsByKey' (expr: Ln 1, Col 5)
-----------------------------------------------------------------------------------
at Enabling Condition (element.tpl:1732)
at Call Stock-Section 'Usage/Definition Location List' (element.tpl:1730)
at Folder Section for 'xs:%localElement' (element.tpl:1694)
at Folder Section (element.tpl:1332)
at Template: C:\test\XSDDoc\lib\element\element.tpl
   with context element: <xs:element name="complexType" type="xs:localComplexType">
   (http://www.w3.org/2001/XMLSchema.xsd)
at Call Template 'lib\element\element.tpl' (FramedDoc.tpl:5124)
at Element Iterator by 'xs:%element' (FramedDoc.tpl:5086)
at Element Iterator by 'xs:schema' (FramedDoc.tpl:5036)
at Template: C:\test\XSDDoc\FramedDoc.tpl
   with context element: #DOCUMENTS

Finding Error Location in Template

FlexDoc/XML templates are plain text files, where every component/property definition starts from a new line. So, having a line number in the template file, you can open it in some text editor and find the necessary line. However, that won't be very useful because templates are not supposed for manual editing.

Instead, using the same line number information, you can quickly find the error location directly in the Template Designer:

  1. Open the template in the Template Designer.
  2. In the main menu select: Edit | Find. You will see a dialog where in «Search for» combo-box should be: Line number in template file
  3. In the «Line Number» field enter the line number (that you took from the ERROR REPORT) and click «Search».
  4. Now, in the «Search Results» pane you should see a tree of some template components. The last node of that tree depicts the component/property that was searched for (corresponding the entered line number). All nodes above are its ancestors (that is all those components that contain the found one). You can walk that tree by clicking with mouse on particular nodes.
  5. When you click «Show Location» button, the Template Designer (behind the dialog) will adjust itself to show the component currently selected in the «Search Results» tree (or when it's a property, then the component containing it). That component will be selected in the designer pane as well. Now you can close the search dialog and edit the selected component or see its properties.
    The selected component is highlighted in the designer pane (on the right) with a faint blue box around it. When it is a template section, it is also highlighted in the section tree (on the left).
Below is the compound screenshot of the whole search process described above (click to see in full size):

See Also:

5. Tips

Here are some tips on various topics of using FlexDoc/XML Generator and the output documents produced with it.

Input XML Files

Using file pathname patterns

When you need to process at once so many input XML files that it is impractical to list all of them as generator arguments, you can use Ant-style file pathname patterns.

Each pathname pattern looks similar to a normal file pathname besides that it may contain some wildcard characters with a special interpretation. These are the following:

Wildcard Description
? matches one character in a real file name
* matches zero or more characters
** when used as the name of a directory, it matches zero or more sub-directories at any depth

File pathname patterns may be both absolute and relative ones, may contain spaces, etc. Basically, they should be specified the same as the ordinary file pathnames.

Example Patterns:

Pattern Description
*.xsd matches all XSD files in the current directory
c:\schemas\*.xsd matches all XSD files in the directory c:\schemas\
c:\schemas\**\*.xsd matches all XSD files in the directory c:\schemas\ and all its subdirectories
c:\**\schemas\*.xsd matches all XSD files found in any directory with the name 'schema' at any depth
../**/*.xsd matches all XSD files found in the parent directory of the current one and all its subdirectories
*.x?? matches all files in the current directory, whose name extension consists of 3 letters starting with 'x'
*.x* matches all files in the current directory, whose name extension starts with 'x'

Notes:

HTML Output

Custom Style Sheet

Since the version 1.9.0 it is possible to substitute some of the generated CSS rules with your custom ones. This allows you to adjust (to some extent) how the generated documentation looks without changing the templates.

For further details, please see: FlexDoc.XYZ | Documentation | Usage of CSS in generated HTML

Inserting "Mark of the Web" comment

When you run generated HTML documentation from a local drive using Internet Explorer with Windows XP SP2, the Information Bar may indicate that active content (the JavaScript in the HTML) has been blocked. To avoid this problem, according to Microsoft, a Mark of the Web (MOTW) comment should be inserted in all generated HTML documents.

FlexDoc/XML is able to insert the generic MOTW automatically (see code below). This is controlled by "Add Mark of the Web" option (see HTML Options Inspector).

You may also program inserting MOTW by yourself using a special HTML pattern file. To do this, you should create a separate HTML file with the following content: 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- saved from url=(0014)about:internet -->
<html>
<head>
<!-- flexdoc-html-head -->
</head>
<body>
<!-- flexdoc-html-body -->
</body>
</html>
Then, specify location of this file in the “HTML pattern file” field within the HTML Options Inspector (or using '-o:html.documentPatternFile' formatting option on the generator command line).

FlexDoc will produce all HTML documents using the specified HTML pattern file with the lines <!-- flexdoc-html-head --> and <!-- flexdoc-html-body --> replaced with the actual generated output.

For more information about MOTW, please see Microsoft MSDN web-site (they frequently change the page location, so here is a Google query): http://www.google.com/#q=Mark+of+the+Web

RTF Output

Updating RTF fields in MS Word

The RTF documentation generated by the provided templates heavily uses document fields (for such things like page number references, number of pages and so on).

When you load the generated RTF in MS Word, to have the fields display the correct values, you will need to update them. To do this, please type: Ctrl+A, then F9.

Including generated RTF in larger Word document

Your task is the following. You have prepared a certain static Word document and need to include into it the output generated with FlexDoc so as each time your XML documentation is regenerated, the larger Word document is updated as well.

Here is how you can do that.

You should insert into your Word document an INCLUDETEXT field. Using the MS Word menu, it may be done like this:

Insert | Field... | Categories: Links and References | Field names: Include Text
In the Word document (when “Toggle Field Codes” switched on), the field will look like the following:
{ INCLUDETEXT "C:\\blah\\blah\\XMLDoc.rtf" \* MERGEFORMAT }
Here, the RTF document generated with FlexDoc should be found by the path:
C:\blah\blah\XMLDoc.rtf
Make sure you use double slashes in the field's pathname (as a single slash is used to start a command or an option)!

After that, you can generate with FlexDoc the XMLDoc RTF. To prepare the result big document, open it with MS Word. Then, press Ctrl+A (select all) and F9 (to update fields).

Including static Word document into generated RTF

Now, the task is the opposite. You have prepared some static Word document and need to include it somewhere in the RTF document generated by FlexDoc.

That is possible too. However, you will need to specify this in some template (because only templates eventually generate any output). Therefore, you will need to use the Template Designer.

In some template location, which is determined by where you need to insert your Word document, you should specify a Data Control as shown on the screenshot (the rectangle with "Include Text ..."):

In the property dialog of that Data Control, you should specify: Data Source = 'Document Field'; Field = 'Include Text', as shown on the next screenshot:

In the “Expression for Filename or URL” field, specify a FlexQuery expression that will evaluate to the pathname or URL of the Word document file you want to include. That expression may be as simple as just a string constant (as shown in the screenshot).

When you generate an RTF file with that template and open it in MS Word, you will see in it a field like this:

After updating that field, your Word document will be included there.

Generating RTF for non-Word applications

The RTF generated by FlexDoc/XML may be successfully imported into OpenOffice.org Writer, Adobe FrameMaker and probably many other (non MS Word) software.

To make the RTF look better in other applications, before generating it, you may uncheck “Tune output for MS Word” option in RTF Options dialog (or using '-o:rtf.tuneForMSWord=false' formatting option on the Javadoc command line).

Here are the details about this option:

When “Tune output for MS Word” option is selected, the generator will adjust some RTF formatting settings specifically for MS Word.

Although Microsoft is the originator of RTF format, the MS Word itself appears to have some oddities of rendering certain RTF settings, even though those settings may well follow the RTF specification. For instance, when displaying the paragraph or table borders, their horizontal positions may be shifted (e.g. when MS Word interprets horizontal margins of a paragraph, it draws the paragraph borders and paddings within the specified margin space but not within the paragraph content as it might be natural).

To overcome this, in such cases, we adjust the initial dimensions in the opposite way so as the result formatting would look properly in MS Word (e.g. to make the actual paragraph margin look as intended the margin width specified in RTF is increased by the paragraph border and padding widths).

However, when you generate RTF to display it primarily not in MS Word but rather in different viewers or editors (e.g. OpenOffice.org under Linux), which interpret the original RTF specification more literally, those specific adjustments may cause a visible distortion of the intended formatting of the document. In such cases, we recommend to uncheck this option.

If something is wrong with the imported RTF, try also to uncheck “Include paragraph style” and “Include character style” options. Some tools have problems with the formatting styles embedded in RTF.

At last, very important. Most of non-Word applications cannot handle nested tables in RTF. (For instance, FrameMaker 8 simply hangs during importing any RTF that contains nested tables.) Generation of nested tables is not specifically controlled by the RTF options of the generator. Instead, it is programmed entirely in templates (e.g. XSDDoc). We frequently use nested tables to organize grid layouts so as to place information more compact on the page. Those templates normally include an alternative implementation without nested tables, which is activated by a special template parameter. For instance, in the case of XSDDoc templates, this is “Formatting | Allow nested tables” parameter.