java [java_options] <class_path> <generator_class> [options] [XML files]
where
java is the Java Interpreter located at 'bin' directory of
JDK/JRE installed on your system.
<java_options> are the Java machine options.
When you are going to process large quantities of data (e.g. big XML files or a lot of them at once), 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.
<class_path> is the DocFlex/XML class path which should be the following:-cp lib\xml-apis.jar;lib\xercesImpl.jar;lib\docflex-xml.jar
Note, 'docflex-xml.jar' is the DocFlex/XML Java library, which has different names
in different editions:
| Edition | Library |
|---|---|
| Full Edition | docflex-xml.jar |
| DocFlex/XML (Kit) | docflex-xml-kit.jar |
<generator_class> is this:
com.docflex.xml.Generator
[options] are the Generator command line options you need
[XML files] specify one or multiple XML files to process
Note: When [options] or [XML files] are omitted,
the generator will try to load all missing settings from the
generator.config file
(see also -config option).
| -config | -f | -nodialog | -template | |
| -d | -format | -O | -xmltype | |
| -docflexconfig | -launchviewer | -P | ||
| -errlog | -M | -quiet |
Please note, options not specified directly on the command line, first, will be searched in the generator.config file and only when not found their default values will be used.
Here are 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 docflex.config file).
-template C:\docflex-xml\samples\sales\sales.tpl
-template XMLDoc.tpl
or
-p:<parameter> <value>-p:includeImages true).
-p:title "My Docs").
-P<parameter>=<value> or -p:<parameter>=<value>
The format was changed in order to have the <value> passed as a separate command-line argument. This is needed for compatibility with Apache Ant (particularly, in some situations when the value string contains spaces).or
-o:<option> <value>-o:rtf.storeGraphicsInRTF false).
-O<option>=<value> or -o:<option>=<value>
The format was changed in order to have the <value> passed as a separate command-line argument. This is needed for compatibility with Apache Ant (particularly, in some situations when the value string contains spaces).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 XMLDoc.tpl -format RTF -d c:\outc:\out\XMLDoc.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
docflex.config
file found near docflex-xml.jar file in the lib directory.
-launchviewer-launchviewer=false
If this option is not provided, the location of the generator config file will be searched in
docflex.config
which, by default, points to 'generator.config' in 'config' directory.
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
docflex.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.
'docflex.config' which is searched in the
directory where the DocFlex Java library file 'docflex-xml.jar' is
located. If not found, docflex.config is created automatically with default settings.
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
“docflex_error.log” name (for example, setting "-errlog ."
will be interpreted as 'docflex_error.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 existed 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).
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 DocFlex 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\docflex-xml.jar
java -cp %classpath% com.docflex.xml.Generator @argfile
argfile may contain the following lines:
-template templates/XMLDoc.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:
In this dialog, you can specify most of the settings needed for the generator as well as to start generation and track its progress.
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 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.
When multiple XML files are specified, the file pathnames should separated with spaces. When a pathname itself contains spaces, 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"
In addition to the local file pathnames, each XML file can be specified with an URL
(e.g. http://www.w3.org/2001/XMLSchema.xsd).
In that case, the generator will try to download such a file directly from Internet.
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:
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.
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.
Here are some tips on various topics of using DocFlex/XML and the output documents produced with it.
DocFlex 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 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.
When the Generator Dialog is enabled, any error is reported via the error message dialog, like the one shown on the screenshot:
The error dialog shows brief information about the error. When more details are available, a full ERROR REPORT is created and dumped to the system clipboard. You can easily extract it (e.g. under MS Windows, just run Notepad and press Ctrl+V).
The detailed ERROR REPORT includes:
The RTF documentation generated by the provided templates heavily uses document fields (for such things like page number references, number of pages and so on).
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:
Insert | Field... | Categories: Links and References | Field names: Include TextIn the Word document (when “Toggle Field Codes” switched on), the field will look like the following:
{ INCLUDETEXT "C:\\blah\\blah\\XMLDoc.rtf" \* MERGEFORMAT }
Here, the RTF document generated with DocFlex should be found by the path:
C:\blah\blah\XMLDoc.rtf
Make sure you use double slashes in the field's pathname
(as a single slash is used to start a command or an option)!
After that, you can generate with DocFlex the JavaDoc RTF. To prepare the result big document, open it with MS Word. Then, press Ctrl+A (select all) and F9 (to update fields).
When you run generated HTML documentation from a local drive using Internet Explorer with Windows XP SP2, the Information Bar may indicate that active content (the JavaScript in the HTML) has been blocked. To avoid this problem, according to Microsoft, a Mark of the Web (MOTW) comment should be inserted in all generated HTML documents.
DocFlex/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> <!-- docflex-html-head --> </HEAD> <BODY> <!-- docflex-html-body --> </BODY> </HTML>
Then, specify location of this file in the “HTML pattern file” field within the
HTML Options Inspector (or using
'-o:html.documentPatternFile' formatting option
on the generator command line).
DocFlex will produce all HTML documents using the specified HTML pattern file with the
lines <!-- docflex-html-head --> and
<!-- docflex-html-body --> replaced with the actual generated output.
For more information about MOTW, please refer to Microsoft MSDN web-site: http://msdn.microsoft.com
Here is an example of how it can be done.
Let's suppose, we want to generate a framed HTML documentation using
XSDDoc | FramedDoc.tpl template
by the XML schema located at the URL 'http://www.w3.org/2001/XMLSchema.xsd'.
We can do this using the following ordinary command line:
java
-Xmx512m
-cp lib\xml-apis.jar;lib\xercesImpl.jar;lib\docflex-xml.jar
com.docflex.xml.Generator
-template templates\XSDDoc\FramedDoc.tpl
-format HTML
-d out
-nodialog
http://www.w3.org/2001/XMLSchema.xsd
build.xml file:
build.xml
|
<?xml version="1.0"?>
<project basedir="." name="XSDDoc"> <property name="cp" value="lib\xml-apis.jar;lib\xercesImpl.jar;lib\docflex-xml.jar"/>
<target name="xsddoc">
<java classname="com.docflex.xml.Generator" classpath="${cp}" fork="true" maxmemory="512m">
<arg value="-template"/> <arg value="templates\XSDDoc\FramedDoc.tpl"/>
<arg value="-format"/>
<arg value="HTML"/>
<arg value="-d"/>
<arg value="out"/>
<arg value="-nodialog"/>
<arg value="http://www.w3.org/2001/XMLSchema.xsd"/>
</java>
</target>
</project>
|
To run this file, you can use a Windows BAT specified like the following:
(Note, it should be started from the directory containing the Antset ANT_HOME=C:\apache-ant set PATH=%ANT_HOME%\bin;%PATH% set JAVA_HOME=C:\jre1.5 call %ANT_HOME%\bin\ant.bat xsddoc
build.xml file!)