java
[java_options]
--module-path <module_path>
--module flexdoc.xml/xyz.flexdoc.xml.Generator
[options]
[XML files]
| Command/Arg | Explanation |
|---|---|
java
|
A system command used to invoke JVM (Java Virtual Machine).
On Windows, that command may be as simple as
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 -Xmx512m will allocate 512 Mb for the heap, which is OK for most purposes (e.g. to run XSDDoc) on 32-bit Java.
For 64-bit Java (running on 64-bit OS), we recommend to double the amount of allocated memory
since lots of internal things (like memory pointers) get doubled in size on 64-bit (as compared to 32-bit OS).
So, on Windows 10 64-bit you should specify |
<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).
On Windows, the FlexDoc/XML module path looks as follows:
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.
|
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:
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.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.:
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:
|
|
-config -d -defaultcatalog -flexdocconfig -errlog -f |
-format -launchviewer -license -m -nodialog -o |
-p -quiet -template -xmlcatalog -xmltype |
Here are the option details grouped by category:
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).
-template C:\flexdoc-xml\samples\sales\sales.tpl
-template SingleDoc.tpl
or
-p:<parameter> <value>"true" and "false" strings
(for example: -p:includeImages=true).
-p:title="My Docs").
or
-o:<option> <value>"true" and "false" strings (for example:
-o:rtf.storeGraphicsInRTF=false).
The output files are distributed in the following way:
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.
-template SingleDoc.tpl -format RTF -d c:\outc:\out\SingleDoc.rtf with the associated files
subdirectory c:\out\XMLDoc_files\ (if any)
-template SalesReport.tpl -format HTML -d c:\out -f MySalesc:\out\MySales.html with the associated files
subdirectory c:\out\MySales_files\ (if any)
-template XMLDocFrames.tpl -format HTML -d c:\outc:\out\
with the main file index.html
-template XMLDocFrames.tpl -format HTML -d c:\out -f MyXMLc:\out\MyXML.html
and all other files located in the directory c:\out\MyXML_files\
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.
Precisely, this command is specified in flexdoc.config
file found near flexdoc-xml.jar file in the lib directory.
-launchviewer-launchviewer=false'urn:flexdoc-xyz:xml:defaultcatalog', which denotes the
default XML catalog
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 more details, please see: Installation / Configuration Files | XML catalogs.
Notes:
-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 ""
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.
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. (See also Error Reporting for more details.)
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).
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
'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.
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:
-license option, that one will be used.
See also Multiple Licenses.
or
-m:<macro> <value>Notes:
-m:LIBPATH="C:\Program 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.
For more details, please see: Installation / Configuration Files | XML Catalogs | Default XML Catalog
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:
set classpath=lib\xml-apis.jar;lib\xercesImpl.jar;lib\resolver.jar;lib\flexdoc-xml.jar
java -cp %classpath% xyz.flexdoc.xml.Generator @argfile
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
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 Generator Dialog can also be invoked from the Template Designer. In that case, the dialog fields are initialized from the default generator.config and the “Template” field is set to the current template open in the 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 Dialog 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).
The combo-box contains the list of the last used templates which allows you to quickly pick one when needed. When the Generator Dialog is invoked from the Template Designer, the “Template” field is preset to the current designed template.
This field duplicate -template option specified on the generator command line.
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.
See also: Multi-valued (List) Parameters | Specifying List Value in Parameter Inspector.
Each file specification must be either:
test1.xml c:\projects\test2.xml "c:\My Projects\test3.xml"
All specified 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 within the XML files being processed.
For more details, please see: Installation / Configuration Files | XML catalogs.
Notes:
If you need to make sure that no XML catalogs will be used (of those left in
generator.config
from the previous GUI settings), just specify -xmlcatalog
option with the empty string argument: -xmlcatalog ""
Similar to the template parameters, the “Options” button near the “Output format” combo-box invokes the Format Option Inspector which is specific for the selected output format.
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.
The following screenshots show the option inspectors for each supported output format:
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 -launchviewer option for more details about this setting.
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 generator 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 some 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.
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).
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” window, when the list parameter is selected:
';' is a separator, the following value item:
red;green;blue
red\;green\;blue
"\\") 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).
Some list parameters can be specified 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 of the value of a list parameter as a whole can be found in the “Parameter Description” window.
For example, suppose you need to pass into a template the list parameter 'gen.doc.element.names' with three value items:
link
target
key
';' is a value item separator):
-p:gen.doc.element.names "link;target;key"
Alternatively, you can pass the same list value using multiple -p options, 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
-p:gen.doc.element.names link;target
-p:gen.doc.element.names key
When the Generator Dialog is enabled, any error is reported via the error message dialog, like the one shown on the screenshot:
=================================================================================== FLEXDOC.XYZ ERROR REPORT, 2016-11-23 18:13:21 =================================================================================== FlexDoc/XML, Version 1.10 Main class: xyz.flexdoc.xml.Generator java.version=1.8.0 java.vendor=Oracle Corporation sun.arch.data.model=64 os.name=Windows 7 os.arch=amd64 os.version=6.1 locale=en_US ----------------------------------------------------------------------------------- GENERATOR INFO ----------------------------------------------------------------------------------- Template Application: XSDDoc Error Demo Main Template: C:\test\XSDDoc\FramedDoc.tpl Loaded XML Files (2): http://www.w3.org/2001/XMLSchema.xsd http://www.w3.org/2001/xml.xsd Output Format: HTML Output Folder: C:\test\out\ ----------------------------------------------------------------------------------- ERROR DETAIL ----------------------------------------------------------------------------------- Generator Exception: No element map found with id 'all-element-usage' ----------------------------------------------------------------------------------- When executing function call 'findElementsByKey' (expr: Ln 1, Col 5) ----------------------------------------------------------------------------------- at Enabling Condition (element.tpl:1732) at Call Stock-Section 'Usage/Definition Location List' (element.tpl:1730) at Folder Section for 'xs:%localElement' (element.tpl:1694) at Folder Section (element.tpl:1332) at Template: C:\test\XSDDoc\lib\element\element.tpl with context element: <xs:element name="complexType" type="xs:localComplexType"> (http://www.w3.org/2001/XMLSchema.xsd) at Call Template 'lib\element\element.tpl' (FramedDoc.tpl:5124) at Element Iterator by 'xs:%element' (FramedDoc.tpl:5086) at Element Iterator by 'xs:schema' (FramedDoc.tpl:5036) at Template: C:\test\XSDDoc\FramedDoc.tpl with context element: #DOCUMENTS
Instead, using the same line number information, you can quickly find the error location directly in the Template Designer:
Each pathname pattern looks similar to a normal file pathname besides that it may contain some wildcard characters with a special interpretation. These are the following:
| Wildcard | Description |
|---|---|
| ? | matches one character in a real file name |
| * | matches zero or more characters |
| ** | when used as the name of a directory, it matches zero or more sub-directories at any depth |
File pathname patterns may be both absolute and relative ones, may contain spaces, etc. Basically, they should be specified the same as the ordinary file pathnames.
Example Patterns:
| Pattern | Description |
|---|---|
*.xsd |
matches all XSD files in the current directory |
c:\schemas\*.xsd |
matches all XSD files in the directory c:\schemas\ |
c:\schemas\**\*.xsd |
matches all XSD files in the directory c:\schemas\ and all its subdirectories |
c:\**\schemas\*.xsd |
matches all XSD files found in any directory with the name 'schema' at any depth |
../**/*.xsd |
matches all XSD files found in the parent directory of the current one and all its subdirectories |
*.x?? |
matches all files in the current directory, whose name extension consists of 3 letters starting with 'x' |
*.x* |
matches all files in the current directory, whose name extension starts with 'x' |
Notes:
'\' or '/') independent on the system.
For further details, please see: FlexDoc.XYZ | Documentation | Usage of CSS in generated HTML
FlexDoc/XML is able to insert the generic MOTW automatically (see code below). This is controlled by "Add Mark of the Web" option (see HTML Options Inspector).
You may also program inserting MOTW by yourself using a special HTML pattern file. To do this, you should create a separate HTML file with the following content:<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <!-- saved from url=(0014)about:internet --> <html> <head> <!-- flexdoc-html-head --> </head> <body> <!-- flexdoc-html-body --> </body> </html>
'-o:html.documentPatternFile' formatting option
on the generator command line).
FlexDoc will produce all HTML documents using the specified HTML pattern file with the
lines <!-- flexdoc-html-head --> and
<!-- flexdoc-html-body --> replaced with the actual generated output.
For more information about MOTW, please see Microsoft MSDN web-site (they frequently change the page location, so here is a Google query): http://www.google.com/#q=Mark+of+the+Web
When you load the generated RTF in MS Word, to have the fields display the correct values, you will need to update them. To do this, please type: Ctrl+A, then F9.
Here is how you can do that.
You should insert into your Word document an INCLUDETEXT field. Using the MS Word menu, it may be done like this:
{ INCLUDETEXT "C:\\blah\\blah\\XMLDoc.rtf" \* MERGEFORMAT }
C:\blah\blah\XMLDoc.rtf
After that, you can generate with FlexDoc the XMLDoc RTF. To prepare the result big document, open it with MS Word. Then, press Ctrl+A (select all) and F9 (to update fields).
That is possible too. However, you will need to specify this in some template (because only templates eventually generate any output). Therefore, you will need to use the Template Designer.
In some template location, which is determined by where you need to insert your Word document, you should specify a Data Control as shown on the screenshot (the rectangle with "Include Text ..."):
When you generate an RTF file with that template and open it in MS Word, you will see in it a field like this:
To make the RTF look better in other applications, before generating it, you may uncheck
“Tune output for MS Word” option in RTF Options dialog
(or using
'-o:rtf.tuneForMSWord=false' formatting option
on the Javadoc command line).
Here are the details about this option:
Although Microsoft is the originator of RTF format, the MS Word itself appears to have some oddities of rendering certain RTF settings, even though those settings may well follow the RTF specification. For instance, when displaying the paragraph or table borders, their horizontal positions may be shifted (e.g. when MS Word interprets horizontal margins of a paragraph, it draws the paragraph borders and paddings within the specified margin space but not within the paragraph content as it might be natural).
To overcome this, in such cases, we adjust the initial dimensions in the opposite way so as the result formatting would look properly in MS Word (e.g. to make the actual paragraph margin look as intended the margin width specified in RTF is increased by the paragraph border and padding widths).
However, when you generate RTF to display it primarily not in MS Word but rather in different viewers or editors (e.g. OpenOffice.org under Linux), which interpret the original RTF specification more literally, those specific adjustments may cause a visible distortion of the intended formatting of the document. In such cases, we recommend to uncheck this option.
At last, very important. Most of non-Word applications cannot handle nested tables in RTF. (For instance, FrameMaker 8 simply hangs during importing any RTF that contains nested tables.) Generation of nested tables is not specifically controlled by the RTF options of the generator. Instead, it is programmed entirely in templates (e.g. XSDDoc). We frequently use nested tables to organize grid layouts so as to place information more compact on the page. Those templates normally include an alternative implementation without nested tables, which is activated by a special template parameter. For instance, in the case of XSDDoc templates, this is “Formatting | Allow nested tables” parameter.