FlexDoc/XML - Generator

Launching Generator from Command Line

Java Command Line

To start the FlexDoc/XML Generator, use the following command (applicable with Java 11 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, it may look like:

"C:\Program Files\Java\jdk-24\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 -Xmx4096m will allocate 4096 Mb for the heap, which is enough to run everything smoothly (e.g. XSDDoc) on 64-bit Java (running on 64-bit OS).

<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.
See Also: FlexDoc/XML | Generator | Input XML

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 further details, please see: Input XML | XML Catalogs

Notes:

  • Besides the command-line option, XML catalogs can be equally assigned using generator GUI; see Input XML | XML Catalogs | 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 GUI.

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. For more details, see also: Generator | Error Reporting

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