Site Map   PRODUCTS ----------------------------------- DocFlex Technology    About    Key Features    Data Processing    Formatting    Templates / Designer GUI    Documentaion   DocFlex/XML    About    Documentaion        Installation & Config Files        Running Generator         Designing Templates    Sample        XMLDoc        Sales Report        Alternative to XSLT    XSDDoc        Features        Organization        Examples        Templates            Subtemplates            Parameters        FAQ    Integrations        Apache Ant        Apache Maven        XMLSpy    Tutorials   DocFlex/Javadoc    About    Documentaion    Templates    Examples    Tutorials   DocFlex/Together    About    Examples    Basic Templates    Documentaion    Tutorials   TRY ----------------------------------- Downloads Registration Trial License   BUY ----------------------------------- Licensing/Pricing Shop   COMPANY ----------------------------------- News Products Services Customers About Us Imprint Legal    Terms of Use    Business Terms & Conditions    End User License Terms Contact Links

DocFlex/Javadoc - Documentation

1. Overview
2. Running Doclet
   • Command Line Options
     • Template Options
     • Output Options
     • Configuration Options
     • Other Options
3. Doclet GUI
   • Specifying Template
     • Setting Template Parameters
   • Selecting Output Format
     • HTML Option Inspector
     • RTF Option Inspector
     • TXT Option Inspector
   • Specifying Output Location
   • Starting Generation
     • Generation Phases
4. Multi-valued (List) Parameters
   • Specifying List Value in Parameter Inspector
   • Using Escapes
   • Specifying List Parameter on Command Line
5. Error Reporting
6. Configuration Files
   • docflex.config
   • docflex.license
   • designer.config
   • generator.config
7. Integrations
   • Apache Ant
   • Apache Maven 2
   • Eclipse
8. Tips
   • Troubleshooting
     • Cannot find doclet class
     • DocFlex doclet is too slow
   • HTML Output
     • Inserting "Mark of the Web" comment
   • RTF Output
     • Getting your images into RTF
     • Updating RTF fields in MS Word
     • Including RTF in larger MS Word document
     • Generating RTF for OpenOffice.org
   • Using Standard Templates
     • Omitting package qualifiers
     • Excluding classes/methods/fields with a custom tag/annotation
     • Migrating to a new version of standard templates

1.  Overview

1. DocFlex Doclet
2. Template Designer

And this may be just enough to make a real use, since DocFlex Doclet coupled with a proper set of templates basically does the same as any other Javadoc doclet: consumes options from the Javadoc command line and generates the output.

So, once provided with the ready templates, you could immediately start generating documentation (programmed in those templates) in any output format supported by the DocFlex core.

Such a standard set of templates is included in both packages available for downloads: “DocFlex/Javadoc” (the full edition) and “DocFlex/Doclet” (the reduced edition). See Examples to take a look on the output those templates produce.

Note:

The DocFlex/Doclet edition is available for free use. It does not include the Template Designer. The templates are embedded in the jar-file included in the package. This product can be used both as a ready to use RTF doclet for Javadoc Tool able to generate an excellent quality MS Word and OpenOffice.org friendly documentation plus a freeware interpreter for your custom templates.

2.  Running Doclet

-docletpath {pathname of docflex-javadoc.jar or docflex-doclet.jar}
-doclet com.docflex.javadoc.Doclet

Other options are described below.

Command Line Options

-config	-f	-link	-P
-d	-format	-linkoffline	-quiet
-docflexconfig	-launchviewer	-nodialog	-template
-errlog	-license	-O

The number of options is relatively small for two reasons:

1. Since all informative content of the generated documentation is programmed entirely within templates, it is the matter of template parameters to control this. The templates parameters are passed via the -P option.

2. The output formats do have their specific options. But since such options are different for each particular output format and the number of supported formats will grow, all output format options are specified in the uniform way via -O option (the same as the template parameters).

Here are the option details grouped by category:

Template Options

-template <file>

Specifies the main template file to be executed by the generator. All documentation generation 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).

-P<parameter> <value>

or

-p:<parameter> <value>

Specifies the value of a template parameter.
Notes:

• You can find the necessary parameter names in the Template Parameter Inspector invoked from the Generator Dialog.
• The boolean values should be specified as "true" and "false" strings (for example: -p:include.deprecated true).
• There are also enum parameters, which are strings limited to only fixed number of values. You can see all possible values accepted by an enum parameter in Parameter Inspector.
• Now DocFlex supports multivalued (list) parameters, which can be equally specified on the command line using this option. See Specifying List Parameter on Command Line for more details.
• When the parameter value contains spaces, enclose it in double quotes (for example: -p:title "My Docs").
• Formerly, this option had the following format (which is also recognized now):

  -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).

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:

• You can find the necessary option names in the Format Option Inspector invoked from the Generator Dialog.
• The values of the boolean options should be specified as "true" and "false" strings (for example: -o:rtf.storeGraphicsInRTF false).
• Formerly, this option had the following format (which is also recognized now):

  -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).

-d <directory>

Specifies the destination directory for the generated documentation. By default, this is the current directory (the one designated by "." pathname). This option works in conjunction with the -f option.

The documentation files are distributed in the following way:

• In the case of a single-file documentation
  1. The output document is placed in the destination directory under default file name 'templatename.formatextention' (for example, in the RTF output format, template PlainDoc.tpl will produce document 'PlainDoc.rtf'). The -f option may override this name.
  2. 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
  1. 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'. This is the same as the output produced by the Standard Javadoc doclet.
  2. 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 Java sources (e.g. by different templates or with the different parameters).

Examples:

-template PlainDoc.tpl -format RTF -d c:\out

generate the document file c:\out\PlainDoc.rtf with the associated files subdirectory c:\out\PlainDoc_files\ (if any)

-template PlainDoc.tpl -format HTML -d c:\out -f OpenAPI

generate the document file c:\out\OpenAPI.html with the associated files subdirectory c:\out\OpenAPI_files\ (if any)

-template FramedDoc.tpl -format HTML -d c:\out

generate the framed documentation located in the directory c:\out\ with the main file index.html

-template FramedDoc.tpl -format HTML -d c:\out -f OpenAPI

generate the framed documentation with the main file c:\out\OpenAPI.html and all other files located in the directory c:\out\OpenAPI_files\

-f <file>

Specifies the documentation 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 documentation (for example, 'DocletAPI'). 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 to view HTML documentation).

Precisely, this command is specified in docflex.config file found near docflex-javadoc.jar (or docflex-doclet.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

Configuration Options

-config <file>

Specifies the generator config file, which may contain options written manually or using the Generator Dialog. All options not provided directly on the command line are looked for in this file.

The Generator Dialog also uses this file to store all options and parameters specified interactively. If the config file does not exist, the Generator Dialog will try to create it by the provided pathname.

By default, the location of the generator configuration file is specified in the docflex.config (located in lib directory). If no other config file is provided, it is automatically loaded from that location (if found).

-docflexconfig <file>

Specifies an alternative path to the DocFlex main configuration file. By default, this file is 'docflex.config' which is searched in the directory where the DocFlex Java library file 'docflex-javadoc.jar' (or docflex-doclet.jar) is located. If not found, docflex.config is created automatically with default settings.

-license <file>

Specifies the location of the license file.

You may need this option when you use the full edition of DocFlex/Javadoc and your license allows you to execute your templates only in its presence. At that, the way how the license is searched by default does not fit to you (see Configuration Files | docflex.license).

Note: The license directly specified with this option on the command line will override any other licenses (e.g. assigned in docflex.config or found near docflex-javadoc.jar).

Other Options

-link <extdocURL>

Creates links to existing javadoc-generated documentation of external referenced classes.

This option will work the same as the -link option supported by the Standard Doclet.

Precisely, the processing of both -link and -linkoffline options is programmed within the templates using a Javadoc-specific FlexQuery function: getExternalDocURL(). When DocFlex/Doclet meets either -link or -linkoffline option on the Javadoc command line, it processes such an option so that the content of the package-list file referred from it is loaded into a special internal hash-table. Further, getExternalDocURL() function uses that table to translate any Java qualified name into a possible URL of the external documentation.

-linkoffline <extdocURL> <packagelistLoc>

This option is a variation of -link; they both create links to javadoc-generated documentation for external referenced classes. Use the -linkoffline option when linking to a document on the web when the Javadoc tool itself is "offline" -- that is, it cannot access the document through a web connection.

This option will work the same as the -linkoffline option provided by the Standard Doclet. See also -link option for more details about how it is implemented.

-nodialog[=<true | false | quiet>]

Do not invoke the Doclet GUI.

Parameters:

true	-	if this (or no parameter) is specified, the DocFlex Doclet starts the generation immediately according to the setting specified on the Javadoc command line and loaded from the generator config (see -config option). Then, the doclet exits.
false	-	this is the same as when the -nodialog option was not specified at all. The Generator Dialog will be invoked.
quiet	-	start the generation immediately (without dialog) and suppress displaying most of the generator messages to screen (see also -quiet option). The generation progress counter will be printed.

-errlog <file>

Specifies the error log file used when the DocFlex Doclet 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).

-quiet[=<true | false>]

Suppress displaying most of the generator messages to screen.

Note: Since Java 5, this option is used by Javadoc itself as one of its core options. If you want to suppress only DocFlex Doclet messages but still see the generation progress counter, use -nodialog=quiet option instead.

3.  Doclet GUI

If no -nodialog option specified on the Javadoc command line, when the DocFlex Doclet starts, it invokes the following dialog:

Specifying Template

This field duplicate -template option specified on the generator command line.

Setting Template Parameters

The bottom panel displays the description of the selected parameter (which is also obtained from the template). The first line of the description (the white text) shows the internal parameter name. Use this name in the -P option to specify the parameter value on the Javadoc command line.

See also: Multi-valued (List) Parameters | Specifying List Value in Parameter Inspector.

Selecting Output Format

• HTML
• RTF
• TXT

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 the generation has finished or cancelled, the Generator Dialog transforms itself back to the initial state. Then, the new settings can be entered and the generation started again. At that, the Java sources information provided by Javadoc via Doclet API remains the same (as Javadoc doesn't care what exactly a particular doclet is doing with it). This allows you during the same session to generate different kinds of documentation by different templates, in different output formats and so on.

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

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 huge project (plus a slow computer), it may last several 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.

4.  Multi-valued (List) Parameters

List parameters allow you to pass into template the whole vector of different values associated with the same parameter name. This provides a universal mechanism for implementing a user control over how a set of templates processes a certain type of data (or situations) that may come in unlimited number of variations.

Before this, such functionality was actually emulated with a string parameter, whose value was expected to contain separate items delimited with a special character (e.g. semicolon). That representation was parsed in a template so as to produce from it an array of values that could be used in further processing. For example, so was implemented (before v1.5.6) the processing of exclude.byTags.classes and omit.packageQualifiers.for parameters of the standard template set.

Now, the parameter inspector also 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 any longer 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

You can see all available value item separator characters in the “Parameter Description” window, when the list parameter is selected:

Using Escapes

my;odd;tag

my\;odd\;tag

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.

As an example of extensive usage of escapes, see description of include.tag.custom parameter of the standard template set.

Specifying List Parameter on Command Line

For example, suppose you need to pass into a template the list parameter include.tag.custom with three value items:

prjtype:a:Project Type:
todo:cmf:To Do:
priority:cmf:Priority

-p:include.tag.custom "prjtype:a:Project Type:;todo:cmf:To Do:;priority:cmf:Priority"

Alternatively, you can pass the same list value using multiple -P options, each one for a separate value item. e.g.:

-p:include.tag.custom "prjtype:a:Project Type:" -p:include.tag.custom "todo:cmf:To Do:" -p:include.tag.custom priority:cmf:Priority

-p:include.tag.custom "prjtype:a:Project Type:;todo:cmf:To Do:" -p:include.tag.custom priority:cmf:Priority

5.  Error reporting

1. I/O errors (e.g. invalid file pathnames, disk full, etc.)
2. Template errors (when something is improperly specified in templates).
3. Data source exceptions (in the case of DocFlex/Javadoc, these may be exceptions thrown by the Doclet API).
4. DocFlex core exceptions (may be caused by bugs not discovered and fixed yet).

When the Generator Dialog is enabled, any error is reported via the error message dialog, like the one shown on the screenshot:

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).

6.  Configuration Files

7.  Integrations

To use DocFlex Doclet in a particular system, basically, you need to know how to specify the following settings:

• The doclet class name
• The doclet class path
• The doclet-specific Javadoc options
• The maximum heap size used by the JVM that runs Javadoc (i.e. how to pass to it the -Xmx option).

We have investigated this for three systems:

• Apache Ant
• Apache Maven 2
• Eclipse

Apache Ant

Here is an example.

Let's suppose, we want to generate a framed HTML documentation using FramedDoc.tpl template by the Java source package 'java5' contained in 'demo' directory of DocFlex/Javadoc installation at C:\docflex-javadoc. Here is a simple Windows command file that launches such a generation:

set DFH=C:\docflex-javadoc
javadoc	-J-Xmx512m -sourcepath %DFH%\demo -d %DFH%\out -docletpath %DFH%\lib\docflex-javadoc.jar -doclet com.docflex.javadoc.Doclet -template %DFH%\templates\javadoc\FramedDoc.tpl -p:windowTitle "DocFlex/Doclet Demo" -p:docTitle "DocFlex Ant Demo" -p:include.tag.custom "todo:a:To Do:" -p:include.tag.custom "prj\:type:opt:Project Type:" -format HTML -nodialog -launchviewer=false java5

build.xml

To run that build.xml file, you can use a Windows BAT specified like the following:

set ANT_HOME=C:\apache-ant
set PATH=%ANT_HOME%\bin;%PATH%
set JAVA_HOME=C:\jdk1.6
call %ANT_HOME%\bin\ant.bat demo

Apache Maven 2

First, you need to install the docflex-javadoc.jar (or docflex-doclet.jar in DocFlex/Doclet edition), which includes the DocFlex Doclet executable code, into the Maven repository.

Under Windows, Maven holds its repository in the following directory: C:\Documents and Settings\User Name\.m2\repository\ However, you cannot copy anything to that directory directly. Instead, you should use the Maven install command (plugin).

Anything stored in the Maven repository is associated with a certain artifact. Each artifact is identified by three things: { groupId, artifactId, version }. Those properties need to be specified anywhere you want to use a feature associated with that artifact. (Maven itself does not work with direct file locations!)

With DocFlex Doclet, we shall associate the following artifact identifiers (the version will be the last DocFlex/Javadoc version number):

groupId	=	docflex
artifactId	=	docflex-doclet
version	=	1.5.6

mvn	install:install-file -Dfile=C:\docflex-javadoc\lib\docflex-javadoc.jar -DgroupId=docflex -DartifactId=docflex-doclet -Dversion=1.5.6 -Dpackaging=jar

pom.xml

The complete working example is included in both DocFlex/Javadoc and DocFlex/Doclet archives prepared for downloads.

Eclipse

First, select in the Eclipse main menu the “Project | Generate Javadoc...” item. The following dialog will show up:

1. In the “Javadoc command” field, provide the location of the Javadoc executable in some JDK installed on your system.
2. Select “Use Custom Doclet”.
3. In the “Doclet name” field, specify the name of the DocFlex Doclet main class: com.docflex.javadoc.doclet
4. In the “Doclet class path” field, specify the full pathname of the DocFlex Doclet Java library file: docflex-javadoc.jar or docflex-doclet.jar (depending on the edition). This file is located in the 'lib' directory of your DocFlex/Javadoc (or DocFlex/Doclet) installation.
5. Now, you can click “Next”.

1. In the “VM options” field, you should specify the maximum memory heap size available to the JVM that will run Javadoc (512Mb may be just enough).

   Note: If you leave this field empty, Javadoc (that is the DocFlex Doclet) may slow down very much, especially on a big project, and you may get eventually java.lang.OutOfMemoryError exception!

2. The “Extra Javadoc options” field is for the doclet-specific options. All the command-line options processed by DocFlex Doclet that you may ever need should be specified here!

   In particular, with the -d option you should specify the output directory for the generated documentation.

   Also, unless -nodialog option is specified directly, the DocFlex Doclet will launch the Doclet GUI over Eclipse. (In fact, since Javadoc is run by a different JVM, the Doclet GUI will be completely independent on Eclipse).

   Remember also that all missing options that the DocFlex Doclet may need (including template parameters) will be taken from the generator.config created when the Doclet GUI was invoked the last time. (So, you should not wonder, how DocFlex Doclet knows some specific settings you did not provide to it.)

8.  Tips

Troubleshooting

Cannot find doclet class

Cannot find doclet class com.docflex.javadoc.Doclet

Please, check the following:

1. If you run Javadoc from the command line (or command file), make sure that -docletpath option is specified properly and points to the location of one of the above jar-files. For example:

   -docletpath {docflex-javadoc}\lib\docflex-javadoc.jar

   where {docflex-javadoc} is the absolute pathname of your DocFlex/Javadoc installation directory.

2. If you run Javadoc from Apache Ant, make sure that both name and path attributes of <doclet> element are specified properly. For more details, see Integrations | Apache Ant.

3. If you run Javadoc from Apache Maven, make sure that either docflex-javadoc.jar (or docflex-doclet.jar) has been installed into the Maven repository and you have properly specified <doclet> and <docletArtifact> elements in your project POM file. For more details, see Integrations | Apache Maven 2.

4. If you run Javadoc from Eclipse, make sure that the field “Use Custom Doclet | Doclet class path” in the “Generate Javadoc” dialog is specified with the absolute pathname of docflex-javadoc.jar or docflex-doclet.jar file. For more details, see Integrations | Eclipse.

DocFlex doclet is too slow

If you are not trying to generate the documentation for many thousands Java classes (or running everything on an outdated computer), most likely you have forgotten to specify enough memory for Javadoc.

The same is true even when DocFlex Doclet is not involved at all. You may run Javadoc with the Standard Doclet (that is without specifying any doclets) on a rather big project and it may become very slow too. The cause is the same -- the lack of memory!

Now, you may wonder. You have a lot of RAM installed on your system, e.g. a couple of gigabytes (or even more). Is it not enough?

The problem is that without specifying that memory explicitly, JVM cannot use it. By default, JVM will allocate a heap of 64 MB size and that will be all memory available to any Java application executed by that JVM.

When the application is memory-intensive, it will be allocating lots of objects, discarding some of them later, allocating new ones and so on. When the memory heap is small, JVM will run the memory garbage collection procedure too frequently. It may be resolving eventually each memory request coming from the application. But that will cost many extra operations. Effectively, JVM may end up doing the garbage collection almost all the time. That's why everything gets so slow! If at some point JVM is unable to allocate a necessary memory block it will throw java.lang.OutOfMemoryError exception.

DocFlex Doclet does need memory. First, it needs memory to maintain the virtual XML-like representation of the Doclet API (see Doclet DSM). Additionally, it uses lots of hash-tables to boost performance. So, the default 64 MB heap size is almost never enough.

What you need to do is to notify the JVM (that will run Javadoc with DocFlex Doclet) that it must use 256-512 MB heap size. How to specify this depends on where you run Javadoc:

1. If you run Javadoc from the command line (or command file), make sure that -J-Xmx option is specified with sufficient amount of memory. For example:

   javadoc -J-Xmx512m ...

2. If you run Javadoc from Apache Ant, make sure that maxmemory attribute of <javadoc> element is specified with proper memory size. For more details, see Integrations | Apache Ant.

3. If you run Javadoc from Apache Maven, make sure that you have specified <maxmemory> element with enough memory size in the Javadoc plugin configuration of your project POM file. For more details, see Integrations | Apache Maven 2.

4. If you run Javadoc from Eclipse, make sure that -J-Xmx option is properly specified in “VM options” field of “Generate Javadoc” dialog. For more details, see Integrations | Eclipse.

HTML Output

Inserting "Mark of the Web" comment

Since version 1.3, DocFlex/Doclet is able to insert the generic MOTW automatically (see code below). This is controlled by "Add Mark of the Web" option (see HTML Options dialog).

You may also program inserting MOTW by yourself using a special HTML pattern file. To do so, 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>

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/en/library/ms537628.aspx

RTF Output

Getting your images into RTF

Updating RTF fields in MS Word

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

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

{ INCLUDETEXT "C:\\blah\\blah\\PlainDoc.rtf" \* MERGEFORMAT }

C:\blah\blah\PlainDoc.rtf

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).

Generating RTF for OpenOffice.org

The RTF generated by DocFlex/Javadoc may be open with Linux OpenOffice.org Writer, which renders it almost the same as MS Word (see Examples | RTF in OpenOffice.org).

To make the RTF look better under OpenOffice.org, before generating it, please 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.

Using Standard Templates

Omitting package qualifiers

1. Omit package qualifiers started with
2. Omit all package qualifiers

Excluding classes/methods/fields with a custom tag/annotation

Since version 1.5.2, to that was added a possibility to exclude everything by annotations. See "Exclude by annotations" parameter group (exclude.byAnns.*). Annotations are more cumbersome to use for that purpose. But they can be retained in the compiled classes. So the exclusion will work even when no corresponding Java source code is found on Javadoc source path.

Migrating to a new version of standard templates

Suppose, some time ago you modified the standard templates according to your needs and since then have been (happily) using them. Now, you come to this web-site and notice that the latest version of DocFlex/Javadoc supports a host of new features, which might be interesting to you too (for instance, the full support of Java 5.0).

Of course, you can run your old templates with the new DocFlex Doclet version. But this won't make those new features automatically available to you. First, they must be applied in templates, which are the actual programs that generate everything. (See About DocFlex/Javadoc | How it works | What are templates?)

So, now you need to migrate to the new standard template set and copy to there or replicate all your specific changes necessary for your work. What is the best way to do this?

The safest way would be to replicate all your changes on the new templates.

You may try to mix your old templates with the new ones. But keep in mind that we constantly change something from the version to version.

Some subtemplates depend on other templates that call them. Basically, there are two such dependencies:

1. The template parameters
2. The element maps

The standard template set is organized so that during the first steps each main template calls the init.tpl subtemplate, whose job is to create the element maps. All element maps are global. Further, they are used in many locations across the template set (especially, in class.tpl).

If the structure of some element maps is different from what is expected and used by a template, that template will work incorrectly (or not work at all)!

Note:

Since v1.5.6, all standard templates also include the version number of the DocFlex/Javadoc release to which the particular template set belongs. This may help you to quickly recognize if you have inadvertently mixed the templates from different versions and because of this now experience errors and wrong working of your template application. You can find the version in the 'APP_VER=...' line of each template as well as in the Template Designer | Template Properties Dialog | General tab | Template Application tab.