FlexDoc/XML - Generator

- Launching Generator from Command Line
- Settings & GUI
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:
- Using various options on the command-line
- With the generator.config
- 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
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.
- Switching Between Generator Configurations
- FlexDoc/XML | Installation / Configuration Files | generator.config
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:

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.
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.-template
option on the Java command line or in Generator Dialog).
Each main template effectively represents a separate documentation generator.
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 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:
- local file pathname (or pathname pattern)
- URL
-
test1.xml c:\projects\test2.xml "c:\My Projects\test3.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 FormatsSetting Format Options
The «Options» button near the «Output format» combo-box invokes the Format Option Inspector, like the one shown on this screenshot:
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:
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:
-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"
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 |
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
- 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).