Products         Customers         News         Downloads         Licensing         Shop    

 DocFlex Technology
Overview
Features
Documentation
 DocFlex/XML
Overview
Features
Documentation
Installation & Config Files
Running Generator
Designing
Templates
Samples
Tutorials
XSDDoc
WSDLDoc
Integrations
Bundles
 DocFlex/Javadoc
Overview
Documentation
Basic Templates
JavadocPro
Examples
Tutorials
 DocFlex/Together
Overview
Examples
Basic Templates
Documentation
Tutorials
 Try
Downloads
Registration
Trial License
 Buy
Licensing
Shop
 Company
News
Products
Customers
About Us
Imprint
Legal
Contact
Links
 

DocFlex/XML - Documentation - 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 DocFlex/XML Generator, use the following command:
java [java_options] <class_path> <generator_class> [options] [XML files]
where all arguments are explained in this table:

Command/Arg Explanation
java A system command that starts JVM (Java Virtual Machine).

On Windows, that command may be as simple as 'java' (when you have installed Java properly) or, alternatively, may look like the following:

"C:\Program Files\Java\jre6\bin\java"

(Just do not 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 7 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).

Concerning Windows 7 64-bit itself, DocFlex/XML generator appears to work about 20% faster on 64-bit Java, as compared to 32-bit.

<class_path> Specify DocFlex/XML class path, which should look as follows (Windows platform):

-cp "%DFH%\lib\xml-apis.jar;%DFH%\lib\xercesImpl.jar;%DFH%\lib\resolver.jar;%DFH%\lib\docflex-xml.jar"

where

  • '%DFH%' must expand to the pathname of DocFlex/XML home directory (e.g. C:\docflex-xml)
  • xml-apis.jar, xercesImpl.jar, resolver.jar are Apache Xerces2 Java libraries
  • docflex-xml.jar is DocFlex/XML Java library

Notes:

  • The precise form of the class path depends on the OS. (For instance, on Linux the name-separator is '/' and the path-separator is ':')
  • When an integration with other software system is used, the above class path should also include all additional Java libraries necessary for that integration (e.g. see DocFlex/XML | Integrations | XMLSpy) and all of them should be specified before docflex-xml.jar!
  • When the file pathnames contain spaces, the entire class path should be enclosed in double quotes! (Otherwise, it will be treated as separate arguments.)
<generator_class> The qualified name of the DocFlex/XML generator main Java class: com.docflex.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
{docflex-xml}/config

directory. (Actually, that location is not static. By default, it is specified in the docflex.config found near docflex-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 {docflex-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] Data-source XML files to process. An XML file may be specified as both local pathname and URL.

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 DocFlex/XML Generator recognizes the following command line options:

-config
-d
-defaultcatalog
-docflexconfig
-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 docflex.config file).

Examples:
-template C:\docflex-xml\samples\sales\sales.tpl
-template PlainDoc.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 DocFlex 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 PlainDoc.tpl will produce document 'PlainDoc.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 PlainDoc.tpl -format RTF -d c:\out
generate the document file c:\out\PlainDoc.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 docflex.config file found near docflex-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:docflex-com: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 DocFlex/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 “docflex_error.log” name (for example, setting "-errlog ." will be interpreted as 'docflex_error.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 docflex.config which, by default, points to the file: {docflex-xml}/config/generator.config

-docflexconfig <file>
Specifies an alternative path to the DocFlex/XML main configuration file. By default, this file is 'docflex.config' which is searched in the directory where the DocFlex Java library file 'docflex-xml.jar' is located. If not found, docflex.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 docflex.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 docflex.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 DocFlex 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 DocFlex/XML (on MS Windows platform):
set classpath=lib\xml-apis.jar;lib\xercesImpl.jar;lib\resolver.jar;lib\docflex-xml.jar
java -cp %classpath% com.docflex.xml.Generator @argfile
The argfile may contain the following lines:
-template templates/XMLDoc/PlainDoc.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, DocFlex/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 several XML files to be used as the generator's data source.

When multiple XML files are specified, the file pathnames should separated with spaces. When a pathname itself contains spaces, 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"
In addition to the local file pathnames, each XML file can be specified with an URL (e.g. http://www.w3.org/2001/XMLSchema.xsd). In that case, the generator will try to download such a file directly from Internet.

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:

  • The ordering of the catalogs in the list 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.
  • The list of XML catalog files specified in this dialog will be stored in the generator.config. Those files will be restored again when invoking this dialog next time and used when running the generator (unless -xmlcatalog command line option is specified).
  • The -xmlcatalog option allows you to specify the XML catalog files on the generator command line. It will override the XML catalog settings stored in the generator.config.

    If you need to make sure that no XML catalogs will be used (of those left in generator.config from the previous GUI settings), just specify -xmlcatalog option with the empty string argument: -xmlcatalog ""

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

DocFlex 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, DocFlex/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 the DocFlex/XML Generator and the 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 (when something is improperly specified in templates).
  3. Data source exceptions (in the case of DocFlex/XML, these are exceptions thrown by the Apache Xerces2).
  4. DocFlex core exceptions (may be caused by bugs not discovered and fixed yet).
DocFlex 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).

The detailed ERROR REPORT includes:

  • The general info about JVM, OS, command-line arguments, etc.
  • All available error messages.
  • The Template Location Trace that shows which precisely template component was being interpreted when the error happened.
  • The Java Exception Stack Trace (when the error was caused by some unexpected Java exception).
When the DocFlex Generator is executed without GUI (-nodialog option is specified on the generator command line), by default, all exception/error details are printed to the standard console. However, using -errlog option, you can specify a separate error log file. In that case, the detailed ERROR REPORT will be dumped in that file; only brief messages will get on the console.

5.  Tips

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

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: DocFlex Technology | 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.

DocFlex/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>
<!-- docflex-html-head -->
</HEAD>
<BODY>
<!-- docflex-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).

DocFlex will produce all HTML documents using the specified HTML pattern file with the lines <!-- docflex-html-head --> and <!-- docflex-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 RTF in larger MS 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 DocFlex 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 DocFlex 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 DocFlex 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).

Generating RTF for non-Word applications

The RTF generated by DocFlex/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.

Copyright© 2003-2014 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.