 DocFlex/XML - Documentation - Running Generator
- Launching Generator from Command Line
- Generator GUI
- Multi-valued (List) Parameters
- Error Reporting
- Tips
1. Launching Generator from Command Line
To start the DocFlex/XML Generator,
use the following command:
java
[java_options]
<class_path>
<generator_class>
[options]
[XML files]
where all arguments are explained in this table:
| Command/Arg |
Explanation |
java
|
A system command that starts JVM (Java Virtual Machine).
On Windows, that command may be as simple as 'java' (when you have installed
Java properly)
or, alternatively, may look like the following:
"C:\Program Files\Java\jre6\bin\java"
(Just do not 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 7 64-bit you should specify -Xmx1024m,
instead of -Xmx512m. (For instance, allocating 512 Mb for 64-bit Java heap size
is no longer enough to document big XML schemas using XSDDoc).
Concerning Windows 7 64-bit itself, DocFlex/XML generator appears to work about 20% faster on 64-bit Java,
as compared to 32-bit.
|
|
<class_path>
|
Specify DocFlex/XML class path, which should look as follows (Windows platform):
-cp "%DFH%\lib\xml-apis.jar;%DFH%\lib\xercesImpl.jar;%DFH%\lib\resolver.jar;%DFH%\lib\docflex-xml.jar"
where
'%DFH%' must expand to the pathname of DocFlex/XML home directory (e.g. C:\docflex-xml)xml-apis.jar, xercesImpl.jar, resolver.jar
are Apache Xerces2 Java librariesdocflex-xml.jar is DocFlex/XML Java library
Notes:
-
The precise form of the class path depends on the OS.
(For instance, on Linux the name-separator is '/' and the path-separator is ':')
-
When an integration with other software system is used,
the above class path should also include all additional Java libraries necessary for that integration
(e.g. see DocFlex/XML | Integrations | XMLSpy)
and all of them should be specified before
docflex-xml.jar!
-
When the file pathnames contain spaces, the entire class path should be enclosed in double quotes!
(Otherwise, it will be treated as separate arguments.)
|
<generator_class>
|
The qualified name of the DocFlex/XML generator main Java class:
com.docflex.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:
-
First, it looks whether a setting was specified directly with an
option on the command line.
-
If it wasn't, the generator finds the
generator.config file
and looks for that setting in it.
-
If the setting is not found still, its default value will be used.
That mechanism allows you to greatly optimize your Java command line (or your Ant/Maven build file, respectively).
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
{docflex-xml}/config
directory. (Actually, that location is not static. By default, it is specified in the
docflex.config
found near docflex-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.:
-config {docflex-xml}/config/generator.config
That will reduce most of your command-line options to just one!
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]
|
Data-source XML files to process.
An XML file may be specified as both local pathname and URL.
|
When XML catalogs are used
(see -xmlcatalog option), each XML file URL will be resolved
by those catalogs. This allows you, for instance, to redirect some external file locations
to their local copies on your system.
|
|
Command Line Options
The DocFlex/XML Generator recognizes the following command line options:
Please note that 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 the option details grouped by category:
Template Options
- -template <file>
- Specifies the main template file to be executed by the generator. All what
is generated is controlled by this template. The main template may call from itself
another templates
(subtemplates)
producing either a single output file or multiple files (framed documentation).
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).
- Examples:
-
-template C:\docflex-xml\samples\sales\sales.tpl
-template PlainDoc.tpl
- -P<parameter> <value>
or
-p:<parameter> <value>
- Specifies the value of a template parameter.
Notes:
Output Options
- -format <HTML | RTF | TXT>
- Specifies the output format. By default, HTML.
- -O<option> <value>
or
-o:<option> <value>
- Specifies the output format option.
Notes:
- -d <directory>
- Specifies the destination directory for the generated report/documentation.
This option works in conjunction with the -f option.
The output files are distributed in the following way:
-
In the case of a single-file output
-
The output document is placed in the destination directory under default file name
'template_name.format_extention' (for example, in the RTF output format,
template PlainDoc.tpl will produce document 'PlainDoc.rtf').
The -f option may override this name.
-
All associated files (such as images, if not included in the document) are placed
in the 'docname_files' subdirectory near the main document.
-
In the case of a framed multiple-file documentation
-
By default, all generated files and subdirectories are placed in the specified destination
directory. The frameset file produced by the main template is saved under the name 'index.html'.
-
If a different name 'docname' is specified with the -f option,
the frameset file is saved under this name. All other files and the subdirectory tree are moved into
'docname_files' subdirectory near the frameset file.
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.
- Examples:
-
-template PlainDoc.tpl -format RTF -d c:\out- generate the document file
c:\out\PlainDoc.rtf with the associated files
subdirectory c:\out\XMLDoc_files\ (if any)
-template SalesReport.tpl -format HTML -d c:\out -f MySales- generate the report file
c:\out\MySales.html with the associated files
subdirectory c:\out\MySales_files\ (if any)
-template XMLDocFrames.tpl -format HTML -d c:\out- generate the framed documentation located in the directory
c:\out\
with the main file index.html
-template XMLDocFrames.tpl -format HTML -d c:\out -f MyXML- generate the framed documentation with the main file
c:\out\MyXML.html
and all other files located in the directory c:\out\MyXML_files\
- -f <file>
- Specifies the output file name. This option works in conjunction with the
-d option and specifies the name of the main output file
(the one associated with the main template).
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.
- -launchviewer[=<true | false>]
- Tells the generator to execute a specific non-Java command to launch an external application
able to view the generated result (for instance, an Internet browser for viewing HTML files
or MS Word for RTF document).
Precisely, this command is specified in
docflex.config
file found near docflex-xml.jar file in the lib directory.
- Examples:
-
-launchviewer- Do launch viewer
-launchviewer=false- Do not launch viewer, no matter what's specified in the
generator.config
Processing Options
- -xmlcatalog <file | URI>
- Specifies an XML catalog file.
The option argument may one of the following:
- Local file pathname
- URL
-
An abstract URI
'urn:docflex-com:xml:defaultcatalog', which denotes the
default XML catalog
To specify multiple XML catalogs, use this option several times for each file.
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:
-
Besides the command-line option, XML catalogs can be equally assigned
using generator GUI;
see Generator GUI | Assigning XML Catalog(s).
-
When one or more
-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 ""
-
When multiple XML catalogs
are used, the order in which they are specified
(on the command line or in the GUI)
may be important!
The same URI may have different resolutions according to different catalogs,
but the one will be used, which was found in the catalog specified the first.
- -nodialog[=<true | false>]
- Do not invoke the Generator Dialog.
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.
- -quiet[=<true | false>]
- Suppresses displaying most of the status messages to Java console.
- -errlog <file>
-
Specifies the error log file used when the DocFlex/XML Generator
is executed without the Generator Dialog
(i.e. when -nodialog option is also specified on the command line).
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 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).
Configuration Options
- -config <file>
- Specifies the generator configuration file,
which may contain options written manually or using the
Generator Dialog. All generator options not provided directly
on the generator command line are searched in this file.
If this option is not provided, the location of the generator config file will be searched in
docflex.config
which, by default, points to the file: {docflex-xml}/config/generator.config
- -docflexconfig <file>
- Specifies an alternative path to the DocFlex/XML
main configuration file.
By default, this file is
'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.
- -license <files>
- Specifies the locations of one or many
license 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 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:
This means that when you have placed several licenses for the same product
in various files/locations (where the licenses are searched)
and one license specified on the command line using -license option,
that one will be used.
See also Multiple Licenses.
- -M<macro>=<value>
or -m:<macro>=<value>
- Specifies the value of a macro,
which can be used in
docflex.config and
XML Type Configuration
files to allow configuring them from the command line.
- -xmltype <files>
or -xmlconfig <files>
- Specifies the locations of one or many
XML Type Configuration 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
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.
- -defaultcatalog <file | URL>
-
Specify the location of the
default XML catalog file.
The option argument may be both the local file pathname and a URL.
For more details, please see:
Installation / Configuration Files | XML Catalogs | Default XML Catalog
Command Line Argument Files
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:
- This will run DocFlex/XML (on MS Windows platform):
set classpath=lib\xml-apis.jar;lib\xercesImpl.jar;lib\resolver.jar;lib\docflex-xml.jar
java -cp %classpath% com.docflex.xml.Generator @argfile
- The
argfile may contain the following lines:
-template templates/XMLDoc/PlainDoc.tpl
-p:title="Sales XML Files"
-format RTF
-nodialog
-launchviewer
samples/sales/sales.xsd
samples/sales/sales.xml
2. Generator GUI
Besides the command line options, DocFlex/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:
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).
Specifying Template
In the “Template” field, you should specify the pathname of the main template
to be interpreted by the generator.
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.
Setting Template Parameters
For the specified template, the “Params” button invokes
the Template Parameter Inspector, like the one shown on this screenshot:
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.
See also:
Multi-valued (List) Parameters | Specifying List Value in Parameter Inspector.
Choosing XML File(s)
In the “XML File(s)” field, you should specify one or several XML files
to be used as the generator's data source.
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.
Assigning XML Catalog(s)
When you click the “Catalog” button, the following dialog will appear:
Here, you can add one or more
XML Catalog
files, which may be both local file pathnames and absolute URLs.
The “Include default XML catalog” check-box allows you to add
also the default XML catalog.
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:
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:
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.
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:
HTML Option Inspector
RTF Option Inspector
TXT Option Inspector
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 and the progress panel appears:
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.
Generation Phases
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.
3. Multi-valued (List) Parameters
Since the version 1.7.2,
DocFlex/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 Parameter Inspector dialog, the entite 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” window, 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).
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.
Specifying List Parameter on Command Line
To specify a list parameter on Javadoc 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 a -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 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
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 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.
4. Error Reporting
Both the DocFlex/XML Generator and the
Template Designer
may encounter various unexpected error situations.
During the generation, the unexpected errors and exceptions may arise
because of the following reasons:
-
I/O errors (e.g. invalid file pathnames, disk full, etc.)
-
Template errors (when something is improperly specified in templates).
-
Data source exceptions (in the case of
DocFlex/XML,
these are exceptions thrown by the
Apache Xerces2).
-
DocFlex core exceptions (may be caused by bugs not discovered and fixed yet).
DocFlex tries to catch all such errors/exceptions and report about them along
with the full diagnostics possible (i.e. where exactly and how the error has happened).
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 general info about JVM, OS, command-line arguments, etc.
- All available error messages.
-
The Template Location Trace that shows which precisely template component was being interpreted
when the error happened.
- The Java Exception Stack Trace (when the error was caused by some unexpected Java exception).
When the DocFlex Generator is executed without GUI
(-nodialog option is specified on the generator
command line), by default, all exception/error details are printed
to the standard console.
However, using -errlog option, you can specify a separate error log file.
In that case, the detailed ERROR REPORT will be dumped in that file; only brief messages will get on the console.
5. Tips
Here are some tips on various topics of using DocFlex/XML Generator
and the output documents produced with it.
HTML Output
Inserting "Mark of the Web" comment
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 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
RTF Output
Updating RTF fields in MS Word
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.
Including RTF in larger MS Word document
Your task is the following. You have prepared a certain static Word document
and need to include into it the output generated with DocFlex so as each time
your XML documentation is regenerated, the larger Word document is updated as well.
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 Text
In 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 XMLDoc RTF.
To prepare the result big document, open it with MS Word.
Then, press Ctrl+A (select all) and F9 (to update fields).
Generating RTF for non-Word applications
The RTF generated by DocFlex/XML may be successfully imported into OpenOffice.org Writer,
Adobe FrameMaker and probably many other (non MS Word) software.
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:
|
When “Tune output for MS Word” option is selected,
the generator will adjust some RTF formatting settings specifically for MS Word.
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.
|
If something is wrong with the imported RTF,
try also to uncheck “Include paragraph style”
and “Include character style” options.
Some tools have problems with the formatting styles embedded in RTF.
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.
|
