FlexDoc/XML - Generator

Template Parameters

What are Template Parameters?

Template parameters are those generator settings that are handled entirely in templates. The generator (its Java-hardcoded part) doesn't understand their meaning. It just reads the parameter definitions from the main template and knows from that how to parse their values and pass to the template.

The template parameters can be specified to the generator in two ways:

Through the generator.config, which is edited using the generator GUI. In that case all parameters can be specified interactively in the Parameter Inspector.
Alternatively, any parameter can be specified on the generator command-line using the -p option and parameter's internal name.
That will override any setting of that parameter found in the generator.config

See Also:

Template Parameter Inspector

When in the Generator Dialog you choose the main template and click «Params» button, you will see the the Parameter Inspector as shown on the following commented screenshot:

The Parameter Inspector is constructed by the definitions of the template parameters found in the main template and allows you to specify all of them in the most convenient way. The parameter values are stored in the generator.config file used by the Template Processor (Generator).

If you need to specify some parameter on the command-line, you should use its internal name with the -p option, e.g.:

-p:DiagramKit.show.annotation=full

The internal name can be found in the Parameter Inspector. Just find that parameter in it and select. The internal name (also called simply Parameter Name) will be visible at the top of the bottom «Parameter Description» panel.

Parameter Descriptions

The description of a selected template parameter is shown in the Parameter Inspector's bottom pane. Such descriptions come from special *.htm files stored along with the template set and linked from the main templates. These are not complete HTML documents, but rather texts with HTML markup and other instructions.

The parameters descriptions may include images and lots of hyperlinks. Such hyperlinks may be of the following types:

External links. These are normal Internet web-site URLs. When such a link is clicked, a special OS command is called that should launch a web-browser, to which the URL is passed. The exact command is specified in the flexdoc.config.
Image links. Some descriptions may include small images with the link to a large version of that image stored along with the descriptions. Clicking such a link will cause running an OS command that should launch an image viewer. That command is also specified in the flexdoc.config.
Local description links. When the parameter description is large, such a link will jump to the necessary part.
Links to other descriptions explaining some term/topic in depth, which are also stored along with the template set. When such a link is clicked, the extra description is loaded and added at the end of the HTML document currently displayed in the description pane, which is scrolled to the linked location.
Links to other template parameters. When you click such a link, the referenced template parameter gets selected in the Parameter Inspector. Then, you can return back to the previous parameters (and its previous description position) using the local menu as shown on the following screenshot.

clicking a parameter link and returning back

Finding All Specified Parameters

As the total number of parameters may exceed hundreds, you may want quickly to find which of those parameters are specified. That can be easily done. Just invoke the popup menu over the Parameter Inspector and select the «Show All / Specified...» item. Then, the list of all parameters defined in the template will appear in a separate dialog where, unlike the Parameter Inspector, they will be presented by their actual names (however, follow in the same order). Select the «specified only» radio-button. Then, only specified parameters will be filtered out and shown in red:

From a parameter selected in that list, you can jump back to the corresponding node in the Parameter Inspector's tree by clicking the «Show Parameter» button.

Profile Parameter

Large template sets may expose hundreds of parameters to allow you to customize the generated documentation within a great range of details. However, that requires you to browse the template parameter tree, understand what each parameter means, and specify some of them accordingly.

To help you with that the main template may provide a special profile parameter, which allows you to change lots of other parameters at once so as to adjust everything to a certain predefined documentation structure that may be more suitable for your needs.

It is based on the feature that each parameter has a certain default value that can be calculated dynamically from the values of other parameters. So, it can be programmed that changing just a single parameter would lead to a cascade of changes of many other parameters, according to a certain purpose.

Such a profile parameter appears the first in the Parameter Inspector:

Saving Position

When you close the Parameter Inspector with the «OK» button, not only all parameter values you have changed are saved in the generator.config file. The following things will be saved there as well:

The expand/collapse states of all parameter groups
The size and position on the screen of the inspector window
The widths of inspector columns
The height of description pane

All of that will be restored when you open the inspector dialog next time.

If you close the Parameter Inspector with the «Cancel» button or by escape, nothing of that will be saved.

Multi-valued (List) Parameters

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 the Parameter Inspector, the entire 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» panel, 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).

Many list parameters are defined 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 the full value of a list parameter can be found in the Parameter Description panel.

Specifying List Parameter on Command Line

To specify a list parameter on the Java 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 the -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 option, 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 the 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.