MIF Doclet Home Page

MIF Doclet

Disclaimer - The MIF Doclet is experimental code developed for internal use at Sun and released to the developer community for use as-is. It is not a supported product. Use at your own risk. While we have worked to make it useful, bugs might not be fixed and features might not be added. It might not be updated, and might be re-released with a different implementation or GUI design that is incompatible with the current design.

Contents

Testing Note - The MIF Doclet has been tested with the Solaris version of FrameMaker 5.5. If you test it with other FrameMaker versions and other operating systems and determine that it does or does not work, please let us know so we can mention it.

What is the MIF Doclet

The MIF Doclet is an extension to Javadoc that generates API documentation in MIF (Maker Interchange Format) from declarations and doc comments in source code in the JavaTM programming language. These MIF documents can then be opened in Adobe FrameMaker and optionally converted to PDF, PostScript, Microsoft RTF, Microsoft Word or WordPerfect.

The MIF Doclet works only with version 1.2.2 or later of the Java 2 SDK, Standard Edition.

FrameMaker batch processing programs can automate converting MIF files to other formats, such as FrameMaker native binary format, PostScript and PDF formats. There are two such batch processing programs available: fmbatch and dzbatcher.

The goal was to create a general, flexible MIF Doclet that can be customized for your own FrameMaker styles. It tries to replicate much of the content generated by the standard HTML doclet. However, the page layout has been modified slightly from the standard HTML doclet to reduce vertical space, for print documentation, where page count needs to be conserved. To obtain denser content, we put subheadings and data on the same line where possible (rather than two lines), and eliminated repetition, by removing the "first sentence" from the index. We also added an option to allow removing the "first sentence" from the member summary.

Benefits

The benefits of a MIF Doclet over the standard HTML doclet are: The MIF Doclet has advantages over the tool html2ps in that the MIF Doclet can have custom formatting more suitable for printed documentation, and can handle images and larger numbers of classes.

Features

The MIF Doclet includes these features:

Limitations

Here are some known limitations of the MIF Doclet:

MIF Doclet Syntax

The syntax is basically the Javadoc syntax with the options listed below. You invoke it using the -doclet and -docletpath options.
javadoc -doclet com.sun.tools.doclets.mif.MIFDoclet -docletpath <path> \
        [options] [packagenames] [sourcefiles] [classnames] [@files]
NOTE - The MIF Doclet cannot handle [classnames] with both the -split package and -bookfile options.

MIF Doclet Options

Options provided by Javadoc:

  -overview <file>          Read overview documentation from HTML file
  -public                   Show only public classes and members
  -protected                Show protected/public classes and members (default)
  -package                  Show package/protected/public classes and members
  -private                  Show all classes and members
  -help                     Display command line options
  -doclet <class>           Generate output via alternate doclet     (Note 1)
  -docletpath <path>        Specify where to find doclet class files
  -1.1                      Generate output using Javadoc 1.1 emulating doclet
  -sourcepath <pathlist>    Specify where to find source files
  -classpath <pathlist>     Specify where to find user class files
  -bootclasspath <pathlist> Override location of class files loaded
                            by the bootstrap class loader
  -extdirs <dirlist>        Override location of installed extensions
  -verbose                  Output messages about what Javadoc is doing
  -locale <name>            Locale to be used, e.g. en_US or en_US_WIN
  -encoding <name>          Source file encoding name
  -J<flag>                  Pass <flag> directly to the runtime system

Options provided by the MIF Doclet:

  -d <directory>                    Destination directory for generated files
  -version                          Include @version paragraphs
  -author                           Include @author paragraphs
  -split package|class              Generate one file per package (default) or class
  -includedir <path>                Path where MIF include files are located    (Note 2)
  -textrectid <int>                 Flow text into TextRectID of number <int>
  -tftag <text>                     Flow text into TFTag of letter <text>
  -doctitle <text>                  Include title for the overview page         (Note 3)
  -link <path>                      Create links to excluded classes at <path>
  -bookfile <file>                  Create book file named <file>
  -titlefile <.mif file>            Title file to be included in the generated book file
  -contentsfile <.mif file>         Contents file to be included in the generated book file
  -indexfile <.mif file>            Index file to be included in the generated book file (Note 4)
  -stylemapfile <file>              File that maps internal styles to FM styles
  -batch fmbatch|dzbatcher          Create batch files, then generate and update FM docs (Note 5)
  -membersummary full|compact|none  Generate full, compact or no member summary
  -group <name> <p1>:<p2>...        Group packages together in overview  page
  -nodeprecated                     Do not include @deprecated information
  -noexecutebatch                   Do not execute the batch program                (Note 6)
  -noinheritedsummary               Do not generate inherited member summary info
Notes
1. The -doclet option takes the argument com.sun.tools.doclets.mif.MIFDoclet for the MIF doclet.

2. The -includedir option points to the location of styles.mif, pages.mif, and textflows.mif.

3. The -doctitle text argument is passed through without any processing. Therefore, it should not contain HTML tags. (This is in contrast to the standard HTML doclet, where the -doctitle can contain HTML tags.)

4. If no -indexfile is given, the file index-all.mif is generated to hold the index.

5. If the batch program supplied with -batch is not in the path, then you get an error like "File not found." For more information about the batch arguments, see Install the batch program under Setup.

6. The -noexecutebatch option is useful when you want to create the batch files (with -batch) but not execute them, in case you want to modify them before running them.

Command-Line Help

To display the command-line help specific to the MIF Doclet, as shown above, execute javadoc with the -doclet, -docletpath and -help options. For example:

javadoc \
  -doclet com.sun.tools.doclets.mif.MIFDoclet \
  -docletpath /usr/local/mifdoclet_C/mif.jar:\
              /usr/local/mifdoclet_C/mifoutput.jar:\
              /usr/local/mifdoclet_C/standarddoclet.jar \
  -help

Running the MIF Doclet

Setup

System Requirements: The MIF Doclet will run with v1.2, v1.2.1, v1.2.2 or v1.3 Beta version of Java 2 SDK. The MIF Doclet temporarily includes a jar file that contains necessary changes to the standard doclet, enabling it to run on this wide range of versions.

Perform these steps before running the MIF Doclet:

  1. Download and unbundle the MIF Doclet bundle. This bundle contains two Java archive files: mif.jar and mifdoclet.jar. You can place these wherever you want as long as the -docletpath option points to them. In addition, -docletpath must also point to the standarddoclet.jar file. [NOTE: Eventually, once some internal changes to the standard doclet have been integrated into the latest version of Javadoc, -docletpath will be able to point instead to tools.jar file that comes with Java 2 SDK v1.3, which contains the standard doclet.]

  2. Install the batch program - Printing or conversion from MIF to any format requires either FrameMaker or a FrameMaker batch processing program. If you want to have the MIF doclet do this automatically, you can include the -batch option and supply either fmbatch or dzbatcher. Be sure the program you use is located on your operating system's search path. Here are some more details:

    • The fmbatch program is from Adobe. Ships with FrameMaker. Available only on Solaris.
    • The dzbatcher program is from Miramo and does the same thing as fmbatch, but on more platforms. It uses slightly different syntax for batch commands (using more Windows-like terms: it uses Close <filename> instead of Quit <filename>, and Exit instead of Quit). Available on Windows NT and soon on Solaris.

Running

NOTE - For the list of known bugs, please see Changes and Bugs in MIF Doclet.
The following example executes the MIF Doclet on a sample package (java.applet) on Solaris. In addition to the above setup, it assumes the following:
javadoc \
  -doclet com.sun.tools.doclets.mif.MIFDoclet \
  -docletpath /usr/local/mifdoclet_C/mif.jar:\
              /usr/local/mifdoclet_C/mifoutput.jar:\
              /usr/local/mifdoclet_C/standarddoclet.jar \  

  -sourcepath /java/src/share/classes \
  -includedir /usr/local/mifdoclet_C \
  -overview /java/src/share/classes/overview.html \
  -doctitle "Java Packages" \
  -group "Core Packages" "java.*" \ 
  -membersummary compact \
  -bookfile java.applet.book \
  -batch fmbatch \
  -titlefile /usr/local/mifdoclet_C/titlepage.mif \
  -contentsfile /usr/local/mifdoclet_C/contents.mif \
  -indexfile /usr/local/mifdoclet_C/index.mif \
  -d docs \
  java.applet
If using your own MIF include files, also use -textrectid and -tftag.


Reviewing Generated Output

IMPORTANT - After generating the documents, you should open them in FrameMaker and scan through them visually, looking particularly for two things: Troubleshooting Generated Output

Q. The characters `\\x0d` appear in the generated document. How do I eliminate this?

A. This is often a cross-platform issue. If a file, such as package.html is created on Windows and then the MIF Doclet is run on Solaris, the newline characters appear as `\\x0d`. The current solution is for you to convert the newline characters in the source file to those recognized by the platform that the MIF Doclet is run on.

More technically, the `\\x0d` would be due to a character that exceeds 0x7F in the source file that is not being converted. When the MIF doclet translates text characters from the doc comment to FrameMaker text, it translates the characters into the FrameMaker character formats. So special characters like '\t', '>', '`', '\', '\\' are translated into '\\t', '\\>', '\\Q', '\\q', '\\\\' respectively. Also, if any character value exceeds 0x7F, then it is converted as "\\x" + Integer.toString(c, 16) + " " So, the string "\\x0d" is getting added because of some character in the source file.

Error Messages when Running the MIF Doclet

When running the MIF Doclet, here is a cryptic error message that can occur:
  Executing fmbatch utility on: docs/xxx.book-mif-to-fm.batch
  starting maker ...
  Frame reports error 3 "Error ???"
This happens when fmbatch tries to execute a statement like "Open docs/java.applet.book.mif" when that file is already open. This commonly occurs when someone runs the MIF Doclet, opens up the book file to inspect the files, then runs it again without first closing the book file. To remedy this, close the book file and try again.


Setting Up the Title Page, TOC and Index

Included with the MIF Doclet bundle are the following sample files: The MIF Doclet adds these three files to the book when you use the -titlefile, -contentsfile and -indexfile options along with the -bookfile option. When doing so, it sets them up as follows:

If you use the -batch option (with fmbatch or dzbatcher), the MIF Doclet converts the MIF files to FrameMaker native binary files, and runs "Generate/Update" on the book file to update the entries and page numbers in the TOC and index.

If you want to use your own template in place of these three files, you can adapt it for use with the MIF Doclet. One easy way is as follows, using the TOC as an example:

  1. Start with your TOC template. It can be named whatever you want -- let's call it contents2.mif.
  2. Import the paragraph styles from contents.mif into contents2.mif. Make sure this file contains no generated text (no table of contents entries), except perhaps a title, such as "Contents", and headings and footers.
  3. Run the MIF doclet with the -contentsfile option: -contentsfile contents2.mif.
Running the MIF doclet this way (along with the -batch option) will generate the table of contents with the MIF paragraph styles but with the page layout (page size, margin size, headers, footers) from your template. You can redefine the paragraph styles as you wish.

Alternatively, you can rename the styles in your template to those used by the MIF doclet, or, rename the styles the MIF doclet generates to those that your template uses. This latter technique takes place in the stylemap.properties file.


Creating PDF

To manually create a PDF version of your document, open the document or book file, as you desire, in FrameMaker and choose the PDF option from the Print dialog box. (The MIF doclet is not yet set up for batch printing to PDF due to a bug we have been encountering.)

The MIF Doclet automatically sets up the left-hand TOC list for Acrobat with indentation as follows:

   BookTitle
   TOCHead
   OverviewHead
   PackageHead
      ClassHead
   IndexHead
(The list actually appears in alphabetic order in Acrobat Setup.) You can modify this list as you see fit, according to the Acrobat Setup procedure described later under Creating Templates.

Doc Comment HTML Notation

As is well-documented, doc comments are written in HTML. The current MIF Doclet can parse and convert only simple HTML into MIF. The following lists describe which tags are handled by the MIF Doclet.

Instructions for Using Your Own FrameMaker Templates

You can use your own FrameMaker templates instead of the ones that Sun provides. Your FrameMaker templates can include your own custom styles, master pages and so forth. Using your own title page, table of contents and index is relatively simple, and is described above at Setting Up the Title Page, TOC and Index. To provide your own formatting and page layout for all the pages between the table of contents and index -- that is, the overview, package and class pages -- follow these three basic steps:
  1. Creating templates
  2. Creating three MIF "include" files from your template
  3. Modifying the stylemap.properties file
These step are covered in the following sections, after "include" files are described.

The Include Files

When running the MIF Doclet, you must place three "include" files in the destination directory. You can use the ones provided with the MIF Doclet, for the default styles and page layouts, or create your own "include" files instead, if you want to use your own custom templates.

When you place these three files in the same directory as the generated MIF documents, the process of opening the generated files in FrameMaker (or in fmbatch) causes these three files to be merged into the document, producing the layout and formatting you want. (Each generated MIF file contains three corresponding <include> MIF commands.)

The three include files for the normal body pages are:

The following figure illustrates how a complete MIF file is structured. It delineates which parts of your template will be extracted for the three include files.

<MIFFile>

########################################
                                       #
Control Statements                     #
                                       #
Macro Statements                       #
                                       #
<ColorCatalog>                         #
<ConditionCatalog>                     #
<PgfCatalog>                           #
<FontCatalog>                          # styles.mif
<RulingCatalog>                        #
<TblCatalog>                           #
<Views>                                #
<VariableFormats>                      #
<XRefFormats>                          #
<Document>                             #
<BookComponent>                        #
<InitialAutoNums>                      #
                                       #
########################################

<Dictionary>
<Aframes>
<Tbls>

########################################
                                       #
<Page>                                 #
<Page>                                 # pages.mif
<Page>                                 #
                                       #
########################################

########################################
                                       #
<TextFlow>                             #
<TextFlow>                             # textflows.mif
<TextFlow>                             #
                                       #
########################################

<TextFlow> (last text flow, to delete)

Creating Templates

If you prefer to alter the appearance of the MIF doclet's default format and layout, the first step is to create your own FrameMaker templates. You can have three different templates -- one each for the table of contents, the body pages, and the index. For each template, take any FrameMaker file you want and modify it as you desire. You can modify: The Acrobat Setup determines which headings appear in the left-hand table of contents in a PDF file. To set these headings, in the FrameMaker template, go to Format menu, Document submenu, and choose Acrobat Setup. Move the headings you want to the left-hand list. (You can also set the Acrobat Setup in the Print dialog box.)

The MIF Doclet does not currently support conditional text. The MIF doclet might support other formats we have not tested, such as document properties and color definitions.

Apply to the first page of the template the master page you want to be the default. For example, for the table of contents, we chose "TOC/Index Opener" master page for the first page.

Creating Include Files

This procedure creates the include files (styles.mif, pages.mif, and textflows.mif) necessary for running the MIF Doclet using your own FrameMaker template. Run through the procedure once to generate a set of three include files. This job is easier if the template is relatively empty of text (that is, there is less text to search through).
  1. As described in the previous section, in FrameMaker, create the template as you desire. Save a MIF version of this file.
  2. In a text editor, open the MIF version created in step 1. The remaining steps describe how to extract the three necessary files from this file.
  3. Search for the first <PageType BodyPage> and locate the following <TextRect> statement. Write down the <ID> number for this <TextRect> for later use. (If there is more than one <TextRect> on this, write down the ID of the first one.)
  4. Locate the <TextFlow> associated with the <TextRect> statement from the previous step by searching for "TextRectID xx" where "xx" is the ID number from the previous step. Write down the <TFTag> name of this <TextFlow>. Then delete this entire <TextFlow>, which ends at the closest following comment "end of TextFlow". (This should be the last <TextFlow> in the file.)
  5. Delete all the <Unique num> statements from the file.
  6. Delete <Dictionary>, <AFrames>, and <Tbls> sections entirely (since they are specific to the original content).
  7. Search for "<PageNum" (no trailing angle bracket) and delete all the <Page> sections containing a <PageNum> tag except for the page containing both <PageNum `1'> and <PageType BodyPage>. If there is no such page, renumber the first <PageNum> to 1 and keep that page.
  8. Search for TRNext. For each one with a non-zero value, make sure an <ID> tag exists somewhere in the file with the same ID number. If such an ID tag does not exist, change the TRNext value to zero, as in <TRNext 0>.
  9. Create a new file called styles.mif and copy into it all the content starting from the second line (just below <MIFFile>) down to but not including the first <Page> tag.
  10. Copy all <Page> definitions to a new file pages.mif.
  11. Copy all <TextFlow> definitions to a new file textflows.mif.
  12. Move all three files to the MIF Doclet's destination directory (specified by the -d option).
At this point, the three MIF include files are created. To use these files, you must include the -textrectid and -tftag options with the corresponding values written down in the previous steps.

Generated MIF Structure

The MIF Doclet generates MIF files that have the structure shown in the following box. The generated <TextFlow> uses the TextRectID number and TFTag name passed in from the respective -textrectid and -tftag options.

<MIFFile 5.50>
include (styles.mif)
### Dictionary, AFrames, Tbls generated from your application follow ###
<Dictionary
...
>
<Aframes 
 <Frame 
 ...
>
<Tbls
 <Tbl
 ...
 >
>
###
include (pages.mif)
include (textflows.mif)
### TextFlow generated from your application follows ###
<TextFlow
 ...
>


StyleMap File

NOTE - The MIF Doclet contains a built-in copy of the default stylemap.properties file. You don't need this file if you are using the default, unchanged MIF Doclet. You need this file only if you are going to modify it, providing different names or mappings of FrameMaker styles.

The MIF Doclet provides a great deal of flexibility in allowing you to name your own FrameMaker styles by allowing you to assign the actual FrameMaker style names it generates. It does this with a stylemap file.

The stylemap file maps internal MIF Doclet style names to FrameMaker style names. You can modify this file to customize the MIF Doclet to use a set of FrameMaker styles from a template your company has already designed.

In the default stylemap, we have tried to maximize the number of internal styles (for maximum flexibility) and yet map those to the minimum number of FrameMaker styles (for simplicity). The initial mapping is about 130 MIF Doclet styles to 61 FrameMaker styles. You can increase the number of Framemaker styles for more refined formatting. You can also modify the entries in the stylemap file to translate the style names.

The MIF Doclet has the default stylemap.properties file built-in. You can copy the stylemap.properties file, then modify the FrameMaker styles names in the right column to those of your choosing. You then load it when you run javadoc using the -stylemapfile option with the filename as its argument. If you named the file stylemap1.properties, you would use the option:

-stylemapfile path/stylemap1.properties
where path is the absolute or relative path to the file. (As with any path, follow it with a forward slash '/' on Solaris or a backward slash '\' on Windows.)

When editing the stylemap file, you should not modify the left-hand column. The hash character '#' indicates the rest of the line is a comment. This comment is optional, and you may omit it. If you want to map to a FrameMaker file that contains a space character, enclose the name in quotes, such as:

PackageHead            "Package Head"        # Name of package, left aligned

Localizing or Customizing Static Text
(mifdoclet.properties)

Some text that is displayed in the generated files does not come from the source files, but instead comes from the MIF doclet. For example, the word "Overview" on the Overview page. Such text resides in the mifdoclet.properties file. This file resides in mifdoclet.jar. To modify the properties file, unjar mifdoclet.jar, modify the text (as described below) and then jar the file back up.

This properties file is very similar to the properties file for the standard doclet. Each entry in this file contains a variable name, an equal sign (=), followed by its value. The word "Overview" appears as follows:

mifdoclet.Overview=Overview
You may change the word on the right of the equal sign as you desire. For example, if you prefer to use the term "Package Set" instead of overview, you could alter it to:
mifdoclet.Overview=Package Set

javadoc-tool@sun.com
Last modified: Wed Sep 1 18:13:01 PDT 1999