Site Map   PRODUCTS ------------------------------------- DocFlex Technology    About    Key Features    Data Processing    Formatting    Templates/Template Designer    Documentaion   DocFlex/XML    About    Documentaion        Installation & Config Files        Running Generator         Designing Templates    Sample        Sales Report        Alternative to XSLT    XMLDoc        About        Templates    XSDDoc        About        Examples        Templates        FAQ    Tutorials   DocFlex/Javadoc    About    Doclet    Examples    Templates    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 - Doclet

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
   • Running Generator
4. Configuration Files
   • docflex.config
   • docflex.license
   • designer.config
   • generator.config
5. Tips
   • Generation phases
   • Error reporting
   • Getting your images into RTF
   • Updating RTF fields in MS Word
   • Including RTF in larger MS Word document
   • Generating RTF for OpenOffice.org
   • Omitting package qualifiers
   • Exclude classes and methods with a custom tag
   • Inserting "Mark of the Web" comment in HTML

1.  Overview

While using Template Designer to design your own documentation would require some understanding of the DocFlex Technology, running DocFlex Doclet would need to know little more than that described on this page.

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' and 'DocFlex/Doclet'. 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

-doclet com.docflex.javadoc.Doclet

Other options are described below.

Command Line Options

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

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 (same as the template parameters).

Here are 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).
• When the 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 config file is specified in the docflex.config (located in lib directory). If no other config file provided, it is automatically loaded from this location if exists.

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

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

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

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.

Running Generator

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.

4.  Configuration Files

5.  Tips

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.

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

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.

Omitting package qualifiers

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

Exclude classes and methods with a custom tag

This parameter can be used to exclude from the generated documentation classes, fields and methods with specified tags. See the parameter description for more details.

Inserting "Mark of the Web" comment in HTML

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