FlexDoc/XML - Installation / Configuration Files

Installation
Configuration Files

1. Installation

To install FlexDoc/XML on Windows/Linux/maxOS, you should:

Unpack the downloaded flexdoc-xml-1.15.zip archive at some location, which we shall designate as '{flexdoc-xml}'.
Since FlexDoc/XML is a Java application, there must be a Java machine (JVM) installed on your system that would run it. There are two possibilities about that:
1. You use some standard Java already present on your system or installed separately.
  Please note that it must be a Java version 11 or later. Otherwise, FlexDoc/XML won't work.
  Then, you need to edit the corresponding command or shell script files to specify the exact location of your Java. And you can run everything.
2. Alternatively, you can download and use the «FlexDoc JRE» – several custom JVM {OpenJDK+OpenJFX} images prepared for Windows, Linux and macOS. That is particularly important if you want to generate diagrams using the DiagramKit.
  In that case, all necessary command or shell script files are already prepared to run them immediately.
If you have a license file flexdoc-xml.license (received by email), copy it to {flexdoc-xml}/lib directory.
However, other location for the license file are possible.

For further details about the installation, setting up and running various things, please see:

2. Configuration Files

FlexDoc/XML can maintain simultaneously multiple configurations, separately for different template applications.

Every such a configuration is defined by the following configuration files:

flexdoc.config
flexdoc.license
generator.config
designer.config
catalog.xml

In addition, there may be any number of XML Type Configuration Files prepared for particular template applications.

Here are details about each configuration file:

File	Description
flexdoc.config	The *main configuration file. This is the configuration root, which points to the default locations of all other configuration files, folders etc. It specifies: The default generator.config The default designer.config The default location of flexdoc.license The location of the default XML catalog file (see catalog.xml). The location of one or multiple XML Type Configuration Files associated with the given template application or used frequently. That is necessary because the default search procedure for an XML Type file in some cases may fail and specifying it all the time with -xmltype option on the command line may be cumbersome. The default resource directory* It is the location of special library files used by the template application to build the documentation. For instance, the JQuery UI library. Specifically, this is what is returned by the function `getResourceFolder()` available in FlexQuery expressions in templates. The default template directory Used by the generator GUI and Template Designer as the initial file chooser directory. In the Template Designer, it is used also to reduce the template file pathnames shown in the window titles of open templates. When a template is found inside the default template directory, the template pathname will be shown relatively it, which makes the window title more readable. The default output directory Used when no output directory is specified to the generator directly with the -d option or can be found in the generator.config file. The definitions of macros, which can be used in both the `flexdoc.config` itself and all XML Type Configuration Files. An external system command to open a URL or several such commands for different URL types. This is used to launch an external viewer for the generated output files (see also -launchviewer command line option) as well as to handle any other URL open requests (e.g. from external links within various descriptions shown in the generator GUI or Template Designer). The main configuration file is used for read-only and never changed. Location: Specified with -flexdocconfig option both on the Template Designer and Generator command line. Default Location: When the main configuration file is not specified directly on the Java command line or not found, it is searched for under the name `'flexdoc.config'` in the same directory where the FlexDoc/XML Java library `'flexdoc-xml.jar'` is located. If not found, the `'flexdoc.config'` file is created automatically with the default settings.
flexdoc.license	The FlexDoc/XML license file, which you should receive by email. You may copy all your licenses into the same single license file (e.g. in the case of multiple licenses). Location: Assigned in the main configuration file. Alternative Location: Can be specified using -license option on the generator or Template Designer command line. If the license file is not found, it is searched for under the name `'flexdoc-xml.license'` near the FlexDoc/XML Java library file `'flexdoc-xml.jar'`.
designer.config	The Template Designer configuration file. It stores the designer configuration for the recently edited templates. This file is created and maintained automatically. Location: Assigned in the main configuration file. Alternative Location: Can be specified using the -config option on the Template Designer command line.
generator.config	The generator configuration file; used by the Generator to obtain all settings not specified directly on the command line. This file is created and maintained automatically by the generator GUI. It contains: The last used templates The values of template parameters The last used XML files The list of XML catalog files The output directory and file name The output format and its options Location: Assigned in the main configuration file. Alternative Location: Can be specified using the -config option on the generator command line. See Also: FlexDoc/XML \| Documentation \| Generator \| Settings & GUI \| Generator Configuration File
catalog.xml	The *default XML catalog* file, which redirects the external locations of some standard XML schemas found in Internet to their local copies stored in FlexDoc/XML resources. This file is critical for large template applications, like XSDDoc and WSDLDoc! For instance, the "xsddoc" XML Type, on which XSDDoc templates are based, itself is based on the XML Schema for XML schemas: http://www.w3.org/2001/XMLSchema.xsd. If that schema cannot be loaded, the XML Type won't be initialized and XSDDoc won't work; nor can it even be edited in the Template Designer! The default XML catalog was introduced to dynamically substitute the canonical locations of some standard XML schemas (like http://www.w3.org/2001/XMLSchema.xsd) found in Internet with their local copies stored in the FlexDoc/XML resource directory: `{flexdoc-xml}/lib/resources` The location of the default XML catalog is specified in the flexdoc.config. By default, it is the file: `{flexdoc-xml}/lib/resources/catalog.xml` However, that location can be overridden with the -defaultcatalog option both on the Generator and Template Designer command line. The default XML catalog is not activated automatically whenever some XML catalogs might be used. Instead, like all other XML catalogs, it must be selected explicitly (e.g. with -xmlcatalog option or xsd.catalogs property). The difference is that it can be specified not only with its physical URL or pathname (leading to the catalog file itself), but using the following abstract URI: `urn:flexdoc-xyz:xml:defaultcatalog` That URI is recognized by FlexDoc/XML simply as “default XML catalog” (whose actual file is specified in the flexdoc.config). That allows you to select the default XML catalog independently on where it is actually located. For example: `-xmlcatalog urn:flexdoc-xyz:xml:defaultcatalog` Location: `{flexdoc-xml}/lib/resources/catalog.xml` – assigned in the main configuration file Alternative Location: Can be specified using the -defaultcatalog option both on the Generator and Template Designer command line. See Also: FlexDoc/XML \| Documentation \| Generator \| Input XML \| XML Catalogs