FlexDoc/XML - Generator

Settings & GUI

Generator settings are all pieces of information that are passed (explicitly and implicitly) to the Template Processor (Generator), when starting it from the Java command-line, so as to control / influence its working, however without changing any templates.

All generator settings can be specified in different three ways:

  1. Using various options on the command-line
  2. With the generator.config
  3. Using the generator GUI, which acts as both an interractive editor of the generator.config and the generator launcher

Settings Categories

All generator settings are subdivided into three categories:

Category Details
general This includes such things like:
template parameters These are the settings addressed to the specified template set (represented by the main template) and implemented in it.
format options These are the settings addressed to the generator implementation of selected output format (e.g. HTML or RTF). For instance, in the case of HTML, some custom CSS files may be specified through that.

Generator Configuration File

The total number of generator settings may be so large that some kind of automation is needed in order to handle them.

First of all, almost all possible generator settings can be stored in a single generator configuration file. For instance, the one prepared for XSDDoc is found here:

{flexdoc-xml}/XSDDoc/config/generator.config
The generator.config is loaded automatically by the Template Processor always when it starts. Its default location is specified in the FlexDoc main configuration file, or it can be overridden with -config option on the Java command-line.
However, you don't need to edit it manually. Instead, you should use the generator GUI, which serves both as the generator.config's editor and the generator launcher.
See Also:

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 that dialog, you can specify almost all of the settings needed for the generator as well as to start generation and track its progress.

The dialog fields are initialized from the generator.config, to where all edited settings are also saved when you leave this dialog by «Exit» button or start the generation. So, the generator GUI serves as an interractive editor of the generator.config.

The generator GUI can be invoked also from the Template 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 GUI 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.
Main templates are those that can be specified for interpretation directly to the generator (either with -template option on the Java command line or in Generator Dialog). Each main template effectively represents a separate documentation generator.
The combo-box contains the list of the last used templates which allows you to quickly pick one when needed.

This field duplicate the -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.

For further details, please see: FlexDoc/XML | Generator | Template Parameters

Specifying Input 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"
For further details, please see: FlexDoc/XML | Generator | Input XML

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: The command line equivalent of this setting is the -format option.

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.

For further details, please see: FlexDoc/XML | Generator | Output Formats
Setting Format Options
The «Options» button near the «Output format» combo-box invokes the Format Option Inspector, like the one shown on this screenshot:
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.
Although, the format options look similar to template parameters, they are completely different settings separated from templates.

The selection of the output format switches a particular implementation of the output generator, which is hardcoded in Java code. The format options control particular features of that implementation. So, their list is specific to the selected output format.

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 itself 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 (also during the estimation phase).

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 the -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 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 a few seconds (or even 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.

Switching Between Generator Configurations

Using the generator GUI, you can prepare and maintain multiple completely different generator configurations (stored in different generator config files) and quickly switch between them:

Then, when you run the generator without the GUI, you can specify the required generator.config with the -config option on the command line, e.g.:
java %JAVA_OPTIONS% --module-path "%MODULE_PATH%" --module flexdoc.xml/xyz.flexdoc.xml.Generator -nodialog -config "%FDH%\XSDDoc\demo\configs\dita11.config"
The meaning of the config menu items is the following:

Menu Item Description
Load Settings Load all generator settings from a chosen generator.config file
Save Settings Save all current settings to the current generator.config, which is the one that was read or saved the last time.

That is frequently done automatically anyway, for instance, when you change template parameters, format options or start the generation.

Save As Save all current settings to a chosen/specified generator.config, which will become the current one
Save As Default Save all current settings to the default generator.config, which the one read the first time.

The default config is specified in the FlexDoc main configuration file, or it can be overridden with -config option on the Java command-line.

How To Suppress Generator GUI?

Of course, in many situations you don't need any GUI, rather just to run the generator itself from Java command line (for instance, when you run XSDDoc as part of some automatic build process).

You can suppress the appearance of Generator GUI using -nodialog command line option. For instance, here is how you should modify the last command in the supplied generator.bat:

java %JAVA_OPTIONS% --module-path "%MODULE_PATH%" --module flexdoc.xml/xyz.flexdoc.xml.Generator -nodialog
In that case
  • The generator will run without any GUI.
  • All generator settings will be loaded from the default generator.config (or the one specified with -config option).

    Using additional options on the generator command line you can specify any other settings that will override respectively those found in the generator.config.

  • All generator messages will be sent to the standard output stream (console).