@return, @param and
@see) that the standard doclet uses.
FrameMaker batch processing programs
enable these MIF documents to automatically be opened in Adobe FrameMaker
and converted to FrameMaker native binary format, PDF or PostScript.
Alternatively, you can manually choose "Save As" to save to
Microsoft RTF, Microsoft Word or WordPerfect.
The goal has been to create a general, flexible means of conversion from doc comments to MIF that can be easily adapted to your own FrameMaker layout, style definitions and book organization. It tries to replicate much of the content generated by the standard HTML doclet. However, the page layout has been modified from the standard HTML doclet to add more layout options and to reduce vertical space, as page count needs to be conserved in print documentation. To obtain denser content, we put subheadings and data on the same line (rather than on separate lines) where possible, and eliminated repetition, such as by removing the "first sentence" from the index. The features list below covers the myriad options.
Changes in this release see the CHANGES file:
Known Bugs and Feature Requests - For a live list of known bugs and feature requests extracted from our database, see the link on the CHANGES page.
Comments, Questions, Suggestions - We'd like to hear from you.
- To send email directly to the MIF Doclet team at Sun, use
.
- To send email to the community of MIF Doclet users, use the MIF Doclet interest group.
License - To view the license for the MIF doclet, open LICENSE.html in the top level of the installed directory.
Sample Generated Books
Examples of books generated with the MIF Doclet:- Sample
Packages book (PDF, 759KB) - The source and generated
files for this book are included in the
testdirectory of this release. - The Real-Time Specification for Java (PDF, 2.7MB),
- Wireless Messaging API (PDF, 770KB)
- Java Card API Specification (PDF, part of download bundle, 2.9MB)
Benefits
The benefits of a MIF Doclet over the standard HTML doclet are:- Easily printable API documents - PostScript and PDF can be
generated from MIF using FrameMaker. With batch processors
fmbatchordzbatcher, you can fully automate this process, printing a set of packages with a single command. - Easily publishable API books - The MIF Doclet can generate headers, footers, a table of contents and an index, with chapter and page numbering, for a complete book. This makes it possible to nearly automate the production of API books.
- Inclusion of API docs into documents written in FrameMaker - MIF-generated API docs can be combined with manually-written FrameMaker documents to make a complete document for distribution. This tightly binds the API and non-API sections for easier download, review and tracking.
- Conversion to other formats - Can manually convert to RTF, Word and WordPerfect using FrameMaker's "Save As" menu option (though this is untested).
Features
The MIF Doclet includes the following features. This summary individually mentions (and has a link to) each of the options (over 80 in number) so that you can get a full picture of what the capabilities are.- FrameMaker, PS and PDF -
Fully automated generation of publication-quality FrameMaker files,
PostScript and PDF from doc comments
(in
.javafiles) and HTML files. The doc comments produce API documentation and the HTML files produce supplemental sections, such as example code, introductions or design descriptions. - Batch processing -
Can use a batch processing program
(
fmbatchordzbatcher) to automate the conversion of the MIF files to FrameMaker native binary files, and generate/update the page break, page numbers, cross-references, table of contents and index. For generating MIF on one machine and converting to FrameMaker on another, you can change paths of filenames from absolute to relative in the generated batch file. - Javadoc tags -
Compatible with doc comments written for the standard doclet.
Uses the same set of
Javadoc
tags (such as
@return,@paramand@see) that the standard doclet uses. Also see Javadoc Tags for a few differences and constraints. - Java and HTML source files - The MIF Doclet supports the same
source files as the standard
doclet, and in addition it can import and convert HTML files
into MIF, resulting in their inclusion in FrameMaker and PDF
documents. HTML files can be imported and converted only when
using an XML Book File, not when using the command line alone.
An HTML file can be included in the
front matter,
chapters or
back matter of a book.
- Many Options -
The MIF Doclet has about 80 options.
See the typical batch example
for the most common command line options. For more complex books,
you may need to use the XML book file describe below.
- FrameMaker book file -
Includes generation of a FrameMaker book file,
making it easy to do book operations (rearrange files,
add chapters, print book). Can arrange files in the book
split by class or package. Can
rename the book file.
- XML book file -
To build a complex book, an
XML book file is available.
This is the XML equivalent of the FrameMaker book file,
specifying the WYSIWYG order that files appear in the book.
This file enables you to do several things you cannot
do with command line options alone: add sections
generated from HTML files,
specify the order of packages and
classes in the API documentation (ordered
rather
than alphabetically).
It lets you specify files in the
front matter,
chapters and
back matter.
You can also specify the equivalent of command line options,
thus reducing the number of options actually used on the
command line to as few as five. See the
XML book file example.
- XML master/subbook files -
A book file (subbook) can include and
override another book file (master book), enabling you to
build a hierarchy of book files. The master book file might
provide the default options, while the subbook provides
the front matter, chapters, back matter, and might override
some options. See the XML
master/subbook example.
- Table of contents and index -
Generates a table of contents and
index of the API with page numbers
and links into the body of text. Index entries automatically
include package, class and members.
- No need to manually open FrameMaker -
You can generate an entire book, complete with title page,
contents, and index, without ever manually opening a FrameMaker
file, even going directly to PDF or a printer. This means
you can fully automate book production by modifying only
options. For example, the options for
booktitle, booksubtitle, bookversion, bookauthor,
bookpublisher, bookcopyright, and bookdedication enable you
to pass these in as strings.
- Almanac -
Generates a concise listing of the API, known as the
almanac, with layout similar to
The Java Developers Almanac by Patrick Chan.
- Include/exclude classes - If you don't want to document entire packages, you can either include only the classes you specify by listing them in the XML book file, or pass in package names and exclude classes from the generated book. As with the standard doclet, you can also include or exclude classes based on access modifiers (public, protected, package, or private). It can also exclude deprecated classes and members.
- Cross-reference links -
Automatically generates internal cross-reference links pointing
to package, class and member specifications, which convert to
links in PDF output. These are links to superclasses, subclasses,
superinterfaces, subinterfaces, implementing classes, inherited
members, overridden methods and so forth. (An ability to
link to external API documents does
not yet work.)
An option exists for omitting
package name prefixes from class names.
The "Link" character style definition is set by default to
blue, no underline. You can modify it to any style in a copy
of
template.mifthat you import.As with the standard doclet, these auto-generated, internal links appear in many places:
- "See Also" sections generated from
@seetags - In-line text generated from
{@link}tags - Exception names generated from
@throwstags - "Specified by" links to members in interfaces and "Overrides" links to members in classes
- Summary tables listing packages, classes and members
- Package and class inheritance trees
- The table of contents and index
Subscript page numbers appear after each internal cross-reference, which is useful for printed documentation where links are not possible. You can easily turn off the subscript page numbers
- "See Also" sections generated from
- Inherit Comments - Operates the same as the standard doclet for
automatic re-use of
documentation comments
- HTML tags -
Enables HTML tags to be used in source
and HTML files to generate the kind of formatting
you want. Converts the most
common HTML tags to MIF, including images, tables, lists,
headings, character styles and entities. The
titles in overview,
package and class sections can be customized.
- HTML hyperlink anchor tags - For
HTML anchor tags
(
<A HREF="ref">), rather than creating a live link, the reference appears as text within parentheses following the label. An option exists for supplying a base URL for converting relative links to absolute links. - GIF images -
Copies GIF images in
<IMG>tags from their source location (inside or outside ofdoc-filesdirectory) to the destinationfm/doc-filesdirectory and imports them by reference. Any files in subdirectories of the originaldoc-filesare all moved directly into the destinationdoc-filesrather than into subdirectories. The image resolution is settable. - Formatting -
Has options for formatting the auto-generated content for
different pages:
- Title page - Enables creating a title page and substituting for placeholders for the book's title, subtitle, version, author, publisher, copyright, and dedication. You can even replace your own placeholders.
- Chapter pages - Can organize the book by chapters, defining each chapter and Section. Can number chapters and substitute the word "Chapter" with any other string.
- Overview page - Can create an overview page that contains a hierarchical class tree, showing the inheritance relationship of the classes. Can group packages together logically on the overview page. Can substitute for the heading "Overview". Can suppress generation of the overview page. Can suppress the generation of the table of packages that would otherwise be located on the overview page.
- Package pages - Can arrange packages alphabetically or logically. Can omit the Class Summary tables from the package pages. Can omit all package pages.
- Class pages - Can arrange classes
alphabetically
or logicallly.
Allows full, compact or no
member summary tables.
Can choose to include the author
and version of the class.
Can omit class hierarchy trees.
Can omit the word "package"
from the title at the top of each package page.
Can omit the package name
(such as
java.lang) from the class name heading -- this reduces redundancy and conserves vertical space if you also modify ClassHead to start "Anywhere" (so classes are not forced to start at the top of a page). - Members (on class pages)- Can sort the members by name or group, alphabetically or in source order. Can specify member headings to have arguments, no arguments, or be the full declarations. Can combine overloaded methods under the common method name heading. Can omit inherited API. Provides a means for specifying the column widths of text for pages of different sizes, and for adjusting the width of the first column in summary tables.
- Constant Values - Generates a list of values for all static constant fields.
- Almanac - Generates a concise almanac listing of the API. Can suppress this from the command line.
- Index - Specifies the alphabetic index, with various index styles: hierarchical, flat, or brief. While this index is two columns by default, you can specify that it be one column.
- Custom FrameMaker templates -
Enables you to modify the FrameMaker template we provide, and
import formats from the custom
template into the book. You can also
provide your own template,
subject to some restrictions. The latter is useful for generating
documents in your own format. You can easily
rename the FrameMaker styles that
the MIF doclet generates, by way of a style mapping properties file.
- Headings -
Enables the inclusion
or omission of the word "Description" as a heading
for description text in overview, package, class and
member sections. Enables the
inclusion or omission of
the word "Declaration" as a heading ahead of the
declaration statement in class and member sections.
- Nested classes -
As with the standard doclet, when documenting a nested class,
the MIF doclet exposes static nested classes the same
as any top-level classes. That is, it includes only static
nested classes in the "Class Summary" on the package page.
Non-static nested classes do not appear in this list, but
are available as members in their enclosing class (as are
all nested classes). In the almanac, both static and non-static
nested classes appear as major headings.
- Since version - The "since" version number derived
from the
@sincetag is included in the generated package, class and member documentation by default. You can suppress this. - Set user variables - You can
define FrameMaker variables
and define values for them. User variables can be used
in body pages or master pages, such as in running
headers or footers.
- Diagnostic aids - The MIF doclet generates a
batch script file that instructs
fmbatchordzbatchershow to execute. You can prevent this script from running so you can modify it and run it manually. - Adapting to batch processor changes - In the unlikely event that the batchfile commands might change, a command is included that loads a file that maps the MIF doclet's batch processor commands to those used by fmbatch and dzbatcher. (Very rarely used.)
System Requirements
The MIF Doclet is 100% Java, and so runs on any operating system where Java platform is installed. It has minimum and recommended system requirements:Minimum requirements - This enables you to generate documentation only as MIF files and not generate FrameMaker or PDF files. This is insufficient for most uses, but can be useful if the source files and FrameMaker are not both available simultaneously. At minimum, you need:
Recommended requirements - This enables you to generate MIF, FrameMaker and PDF files and automate the entire process on Solaris, Windows, or AIX. You will also need:
- Java 2 SDK, Standard Edition, v1.2.2 to 1.4.x. The
javadoctool is installed as part of this SDK.
- FrameMaker 5.5.x or 6.0.x (MIF Doclet has not been tested on earlier or later versions). It runs faster with 6.0 than 5.5. Developers have told us it runs on FrameMaker+SGML as well
- Either
fmbatch(Solaris) ordzbatcher(Windows 2000, NT4.0, Solaris 2.6 or AIX) program as described at Install the batch program- Zapf Dingbats font - Needed only for special characters in the Almanac (symbols for abstract, final, static, protected, constructor and field, and the arrow in the class tree). This font is included with FrameMaker for Solaris and Acrobat for Win32. On Windows, this font is supplied but is not installed. To install it, point Adobe Type Manager to the Acrobat/resource/font/pfm directory and add the fonts found there.
Testing, Memory and Speed
The following table shows the kind of hardware and memory we have used to test the MIF Doclet, and some typical times to generate PDF.Small Document - The MIF Doclet takes 35 seconds to convert the test packages (
com.package1andcom.package2) included in the download bundle running the minimal batch example, as shown in the table below. You can run this test yourself with the included files -- the required batch files and scripts are included.Large Document - As a test for handling large documents, we have run the MIF Doclet on the source code for the entire Java 2 Platform, Standard Edition, v 1.3, which is 77 packages. It took about an hour, as shown in the table below. The largest FrameMaker file was
javax.swing.fmat 11MB.
No. of Java Packages Machine Memory Java SDK Version FrameMaker Version Time to Generate PDF No. of FrameMaker Files PDF Size Small Document 2 packages Sun Ultra 1 SPARC workstation 20MB ( -J-mx20M)J2SE 1.3.0 Solaris FrameMaker 5.5.6 35 sec. 10 files 1 PDF file
67 pages
450kBLarge Document 77 packages Sun Ultra Enterprise 450, 400MHz, high speed disk array and 2GB of physical memory 2000MB ( -J-mx2000M)JDK 1.2.2 Solaris FrameMaker 5.5.6 1 hour 82 files 1 PDF file
12,025 pages
119MBTesting Across Multiple Operating Systems - Sun has tested the MIF Doclet extensively only with the Solaris version of FrameMaker 5.5 and 6.0. We have tested it only briefly with the Windows version of FrameMaker, and are interested in having it well run on all platforms. Many users are using it successfully on Windows. 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 and possibly fix it. (One developer has reported that FrameMaker 5.1 generates "Invalid opcode" errors when opening a MIF file, and the page looks okay except for some extra spacing, but the text cannot be exported to RTF.)
Limitations
Here are some known limitations and restrictions of the MIF Doclet:- Documents Only Packages - You can pass in only package names
and not source filenames (
.java) on the command line. To soften this restriction, the excludeclasses option enables you to exclude classes from the package. - HTML Limitations - As you probably know, doc comments are written
in HTML, not plain text. The MIF Doclet must convert this HTML to
MIF. The current MIF Doclet uses a relatively primitive HTML parser
for this, which slightly limits the HTML that can be converted to MIF.
See Using HTML Tags for more
details.
- Cannot Link to External API Documents - The
-linkand-linkofflineoptions are quite limited in this release. This may be fixed in a later release. - Link Limitations -
Anchor tags
(
<A HREF="ref">label</A>) lose their live link when converted to MIF, FM or PDF, and the reference is printed instead. The reference appears as text within parentheses. For more information, see HTML Hypertext reference anchor tags. - Last Paragraph Style Limitation - The MIF Doclet operates
on one paragraph at a time, and does not look ahead. Therefore,
it currently cannot apply a unique style to the last paragraph
in a series (unless it is in a table). Therefore, it cannot apply
extra space after the last bulleted or numbered paragraph in a series.
- Two Blank Pages Precede Almanac Legend -
The file
almanaclegend.fmcontains two pages: a blank left-hand page followed by the almanac legend on a right-hand page. The styleAlmanacLegendHeadis assigned to start at "Top of Left Page", so it will face the Almanac chapter-opening page. The limitation is that if the previous file ends with a blank left page, you end up with two blank pages in a row. Workaround: Either copy the legend page into the the previous file, or manually adjust the pagination to remove the extra two pages (set Format > Document > Numbering to "Delete Empty Pages"). - Pages Not Generated - By design, the MIF Doclet does not generate all the pages that the standard HTML doclet generates: it does not generate "package use" pages, "class use" pages, "tree" pages, "deprecated API" pages, serialized form pages, or a help page.
- In the list below, this symbol denotes the
command line options for the MIF Doclet.
All command line option names are case-insensitive, though a few arguments,
where noted, are case-sensitive.
- In the list below,
this symbol denotes the command line options for the MIF Doclet.
Using XML book file elements provides more capability
beyond command line options: You can add non-Javadoc
chapters, add appendixes, add sections to the front and back matter,
and sort the packages and classes as desired (command line options allow
only alphabetic sorting). For more details, see
XML Book File.
All element names are case-insensitive, though a few arguments,
where noted, are case-sensitive.
