Changes in MIF Doclet

MIF Doclet Home Page

This document lists the changes in the MIF Doclet from version to version.

Which Version Do I Have? - Version 1.2 Beta 2 is the latest public version. When you run this version, the version number and build date are printed in the console window. The version number "1.2" indicates that the MIF Doclet works with Java 2 SDK v 1.2 (actually 1.2.2) or later. The version will remain "1.2" as long as it remains compatible with Javadoc 1.2.2.

Prominent changes in this release: (1) Works with version 1.4.x of Java 2 SDK, (2) generates a Constant Values page for static fields, (3) implements inherited comments (though not {@inheritDoc}), (4) implements an em-dash, (5) adds strikethrough <strike>and underline <u>, (6) links can now have independent labels, (7) has a -noqualifier option for omitting package names prefixes from class names, (8) -noxrefpagenumber for easily turning off the subscript page number cross-references, and (9) -noclasssummary to omit the Class Summary tables from the package pages. The license has been relaxed to allow users to modify the source code for their own internal use. These and the other changes are described in more detail below.

Upgrading from 1.2 Beta 1: If you use the default template and stylemap.properties, commands used to run version 1.2 Beta 1 of the MIF Doclet should work fine to run version 1.2 Beta 2. We have maintained option compatibility between these versions. However, if you have a custom template or custom stylemap.properties file, please follow the instructions below for updating them.

Bug Database
The following links list the bugs and enhancement requests for the MIF Doclet. "Open" means it is not yet evaluated, fixed, or implemented. "Closed" means it is fixed or implemented, or the report is closed as already fixed, a duplicate, or "will not fix" or "not a bug" -- read the evaluation field to know which one. An enhancement is also known as a "request for enhancement", or RFE, or a feature.

• All bugs and enhancements
  • Open bugs and enhancements
    • Open bugs
    • Open enhancements
  • Closed bugs and enhancements
    • Closed bugs
    • Closed enhancements

Changes to MIF Doclet
Changes in this release follow. In the following list:   = feature,   = bug

Changes to stylemap.properties and template.mif
	Changes to stylemap.properties - Changes to stylemap.properties made between versions 1.2 Beta 1 and 1.2 Beta 2. If you are using a customized stylemap.properties file from 1.2 Beta 1, please make these changes to update it to work with MIF Doclet 1.2 Beta 2.
	Changes to template.mif - Changes to template.mif made between versions 1.2 Beta 1 and 1.2 Beta 2. If you are using a custom template from 1.2 Beta 1, consider making these same changes to update your template for MIF Doclet 1.2 Beta 2.
New Options
	-noqualifier added to specify which package names not to prepend to class names. 4530945    Multiple <noqualifier> options are now cumulative in XML book file 4646371
	-noclasssummary to eliminate Class Summary tables from the package pages. 4644279
	-noxrefpagenumber for removing subscript page numbers. 4521761
	-constantvaluespage to generate a page with values of static constant fields, equivalent to that in the standard doclet. <ConstantsFile> is the XML book file equivalent. 4525023, 4649742
	-sortmembers option has been extended to enable ordering the members in the order they are declared in the source files. The new argument for this is "-sortmembers group:source". 4527367
Running the MIF Doclet
	Enable MIF doclet to run with Java 2 SDK v. 1.4 4521721
	ClassCastException in @throws handling no longer occurs 4645527
	NullPointerException in @throws handling no longer occurs 4645530
	dzbatcher SaveAs error fixed 4399084
Content
	In the inheritance tree, the package name is no longer printed twice when the -excludeclasses option is used. 4531287
	The entity &#151; now prints as em-dash 4676137
	Public, synchronized and native - The MIF doclet now uses the same algorithm as the standard doclet to print the modifiers for each member. For brevity, the summary table does not display "public". It no longer displays implementation-specific modifiers, such as "synchronized" or "native". 4531275
	Array brackets [] in fields are no longer stripped from the field summary table 4531244
	Array brackets [] in method return type are no longer stripped from method signature 4637484
	The "Specified by" sentence in method documentation that states which interface the method is specified by is no longer printed twice. 4531288
	Class name prefix is now added to members in @see tags when the class name is not the same as the current class. This now emulates the standard doclet's behavior. In 1.2 Beta 1, members in @see tags never displayed the class name prefix. (no bug number)
	Implements automatic inheriting of comments 4506740
	List of implemented methods is now computed properly 4531270
	In TOC, numbering chapters no longer numbers front/back matter TOC entries 4516280
	"Methods inherited from interface" now says "class" as it should 4628977
	Now generates interface hierarchy in overview page 4524969
Links
	Links can now have independent labels 4516780. This overcomes the link limitation present in earlier versions: In earlier versions, FrameMaker cross-references had a constraint that when a link refers to a paragraph, that full paragraph must appear as the text that you click on. (This is contrary to HTML, which allows you to specify a separate label. In this version, we use FrameMaker hypertext links to circumvent this limitation. The prior constraint had caused the following limitations:
	Link Labels Ignored - The labels in the @see and {@link} Javadoc tags were ignored. Any use of @see or {@link} to a method or constructor displayed its arguments in the link's text (unless memberhead noargs is used). In the Member Summary tables, the member names could not be made bold. In the "Methods inherited from" tables, the methods that have links had their arguments displayed (in the standard doclet the arguments are not displayed).
	Package qualification in {@link} made consistent 4647370
	Option -noqualifier with {@link} now suppresses package names 4673565
	Subscript page number now displays initially '0' rather than as fully-qualified name 4652163
	Classes passed in but not included in XML file are no longer broken links 4526934
	Links to java.lang in "Overrides" are no longer broken 4530949
	Option -excludeclasses now omits links to excluded classes 4531429
	{@link method text} and {@link method} no longer produce double output 4645236
	Links in member summary table to same package are no longer fully-qualified 4531286
	When the type of a field or the return type of a method is a class or interface in the same package, the unqualified name of the type is now shown in the member summary table. (no bug number)
	Links to "specified by" now go to the interface 4497167
Formatting
	Added <strike> strikethrough and <u> underline 4702258
	COLSPAN in tables now has blank cells for spanned columns 4655470
	Overview tree no longer missing a space ahead of "(implements...)" phrase 4651415
	Constant Values Field entry in table of contents is now formatted correctly 4649175
	For a deprecated class, the text from @deprecated argument no longer appears too large 4650809
	When "-declarationHead none" is used, spacing below ClassHead is no longer 0 4650715
	<H2> in overview.html now maps to ClassSubHead, not ChapterSubHead 4646765
	DocComment table default borders now visible on all cells 4646866
	Reduced default right cell margins from 6pt to 3pt 4650767
	Indented bulleted exception items 4640750
	Provided ConstantsSub*Head styles that map to ClassSub*Head 4649738
	Added internal styles for Overview subhead styles 4646634
	-noxrefpagenumber and "-noqualifier overview-tree" no longer cause rest of tree to be blue 4641662
	Blockquote now mapped properly: some had lowercase 'q', others had uppercase 4645313
	Changed template.mif styles from justified to align left and turned off hyphenation 4643633
	Page numbering now resets properly to 1 at the first chapter 4531267
	Modified almanac legend so it will fit on a single 9" x 7.5" page 4522217
	Error when running fmbatch with constant values page with FM 5.5.6 4648205
Error/Warning Messages
	Improved the warning when path to fmbatch/dzbatcher is not set. (no bug number)
	Added warning when packages in XML book file are different from what's on the command line 4645381
	Removed error message that appears when -batch is omitted 4634754
Compiling Doclet
	NOTE: For those who want to modify the MIF Doclet source code, compiling the MIF Doclet now requires Java 2 SDK v. 1.4.x
	Separated make directory from build directory 4637091
	When only a resource file is changed, gnumake now copies it and builds a new jar file 4648400
	Moved mif version number from mif.properties to its own file 4649361

    mifdoclet-1_2-beta1.zip   3,343,444 bytes

This version has many changes. If upgrading from a previous version, the simplest way to transition is to follow the new examples at Running the MIF Doclet.

        General Changes

• Design change: The three jar files have been combined into one: mifdoclet.jar. (The standard doclet is included because the MIF doclet relies on certain bug fixes in it.)
  Requires changing the argument to -docletpath.
• Stylemap.properties: The stylemap.properties file has changed dramatically. This applies not only when upgrading from version C, but when upgrading from any interim beta version. Having the wrong version can cause bugs to occur.
  Do not re-use the former stylemap.properties file. If you have modified it, bring those changes forward to the new stylemap.properties file.
• Template.mif: The MIF doclet no longer uses the "include" files, but uses a regular FrameMaker (or MIF) file for a template called template.mif. If you have a custom FrameMaker template, you may be able to use it directly.

        Command Line Changes

• Obsoleted options - To help with conversion from earlier versions, see the list of obsolete options and their replacements.
  Requires changing several options and their arguments.
• Design change: Version C required you to supply the -includedir option with these three "include" files. These files have been removed and replaced with a built-in default template that does not require an option to include. A new option -importformats greatly simplifies the process of creating a custom template by allowing you to provide a FrameMaker file (rather than the "include" files) for the template.
• Design change: In version C, if you wanted to run the batch files, you had to supply not only the -batch option but also the -bookfile option. Omitting -bookfile prevented the FrameMaker files from being generated. This dependency has been removed in this version. We also modified -batch so it takes as an argument path/fmbatch or path/dzbatcher. This enables you to specify a particular path for the batch executable.
• Added feature: Added -print option, to fully automate printing directly to printer, PDF or PostScript.
• Design change: Combined all batch files into one for faster execution.

• In FrameMaker 5.5 for Windows, the PDF file cannot be automatically generated -- This appears to be a bug only in the Windows version of FrameMaker 5.5.x, and is fixed in FrameMaker 6.0.
• Tables in package.html produce a NullPointerException. The error occurs when generating the package MIF file. There is no workaround. We plan to fix this in a future version. Write us if you need the fix immediately.
• Tags @see, @since and {@link} in the "Overview" page (overview.html) are not interpreted. For example, "@see #publicStaticMethod()" prints as-is, rather than as "See Also: publicStaticMethod()"
• Image tags <IMG> in overview files (overview.html) are discarded.
• When using an XML book file, image tags <IMG> in an HTML file in <SectionFile> are discarded. Images can be included only in comments in .java and package.html files.
• In an XML book file, if you include multiple <Package> options, you cannot supply a <SectionFile> ahead of each one -- you can supply a <SectionFile> ahead of only the first <Package>, and in that case, the section file's path is relative to the current directory (where you're running the doclet from). You can still intersperse <SectionFile> options between classes. If you omit the <Package> options, you can put <SectionFile> ahead of each list of classes. Workaround: place your text in the package.html file or add the sections manually to the book file after the MIF doclet is done running.
• In the table of contents, if you try to number the chapters, any section files in the front and back matter also get chapter numbers (which they shouldn't). This is because <SectionFile> gets assigned the "ChapterHead" styles regardless whether it falls in <FrontMatter> or <Chapters>. The workaround is to manually create a new style SectionFile that is identical to ChapterHead, and apply that to the headings of the front and back matter sections. (We will eventually probably create a new style called SectionHead that is identical to ChapterHead but gets applied to front and back matter sections. Then ChapterHead could have autonumbering applied to it without affecting front and back matter.)
• The style for table anchors should be ClassTableAnchor. It is currently ClassText-1.
• The <Group> option does not take wildcard (*) while the -group option does. In other words, the former takes only an explicit list of package names, and so is more limited.
• Option "-split class" causes broken links in overview.fm for the package names.
• The Almanac legend does not have symbols for private or package-private API
• The reference page is missing "lib" from -docletpath. The examples should show: -docletpath C:\mifdoclet1.2\lib\mifdoclet.jar
• Cross-references are used where hypertext markers should be used. This means the label is restricted to the text being cross-referenced. If hypertext markers were used, the user could specify the label independently (and it might also be that these would convert to live links in PDF).

• See Limitations

                         Size   Date          Time
    mif.jar              84135  Aug 30, 1999  16:34
    mifoutput.jar        36075  Aug 30, 1999  16:22
    standarddoclet.jar  162636  Aug 31, 1999  16:34

        Command Line Changes

• Design Change: The file standarddoclet.jar is now included by necessity, since some changes in it are required by the MIF Doclet. This means the MIF doclet can work with Java 2 SDK v1.2 and no longer requires v1.2.2. The MIF Doclet also works with v1.3 Beta. Eventually the MIF Doclet will work with tools.jar in v1.3 Final without requiring this separate jar file.
  Requires changing tools.jar to standarddoclet.jar (and its path) in the argument to -docletPath.
• Design Change: Changed the name of the jar files: mif.jar became mifoutput.jar and mifdoclet.jar became mif.jar.
  Requires changing these filenames accordingly in the argument to -docletPath.
• Design Change: Changed the name of the package in which the MIF Doclet code resides.
  Requires changing the -doclet argument to: com.sun.tools.doclets.mif.MIFDoclet.
• Added Feature: Added ability to batch process on Windows NT in addition to Solaris.
  You can add -batch option with one of two arguments: fmbatch or dzbatcher.
• Added Feature:Added required option -includeDir for specifying the directory of the three MIF include files. (This was actually in version B but was undocumented.)
  Requires adding option -includeDir
• Added Feature: Added -noexecutebatch option.

• Added Feature: Alphabetically sort rows in class summary (on package page) and member summary (on class page)
• Fixed Bug: The bug was that {@link name label} tags displayed the name rather than the label. The fix is to omit all HTML tags in the label and display the text that's left.
• Fixed Bug: Parameter names are now included in the Constructor/Method Descriptions.
• Fixed Bug: Fixed bug about @exception tags. Those were getting repeated.
• Fixed Bug: Fixed "missing space" problem after first word in the next paragraph after </p> and </pre> tags.
• Fixed Bug: Added escape character ('\') to any array square brackets [] that appear in Marker Text, like this: '\[' and '\]'. This allows index entries that contain square brackets, such as arrays, to appear properly in the index.
• Fixed Bug: The stylemap.properties file now can have blank lines
• Fixed Bug: Added PackagePreHead to stylemap.properties. Renamed ClassPackageHead to ClassPreHead.
• Fixed Bug: Fixed template.mif so it would no longer display an "unavailable font" warning when opened in Solaris.

• Known Bug: The -includedir option doesn't always seem to copy the styles.mif, textflows.mif, and pages.mif files to the destination directory. Workaround is to omit the -includedir option and instead manually copy those files into the destination directory before running the MIF doclet.
• Known Bug: TrueType fonts in the header/footer are corrupted with Distiller 3.0. (Workaround: Change fonts or use Distiller 4.0 instead.)
• Known Bug: The paragraph ahead of tables is Paragraph style; should be ClassText style.
• Known Bug: When converted to PDF, links in the index appear in the white space to the right of the page number.
• Known Bug: When the table of contents (which has roman numeral page numbers is included in the book, the first page after the contents is not set to page 1.

                   Size   Date          Time
    mif.jar        31977  Jul 20, 1999  16:06   (unchanged from version A)
    mifdoclet.jar  93524  Jul 29, 1999  11:43

• Change: Removed -contentstitle and -indextitle options, which are obsoleted by -contentsfile and -indexfile.
• Fixed Bug: The bug was that the references to .mif files should instead be to .fm files.
• Fixed Bug: The bug was that a space was missing between words. This occured at the boundary of newlines in doc comments.
• Fixed Bug: The bug was that OutlineHead style was white font; should be black.
• Fixed Bug: The bug was that Array brackets [] did not appear in the return type.

• Known Bug: When converted to PDF, links in the index appear in the white space to the right of the page number.
• Known Bug: {@link name label} tags display the name rather than the label.
• Known Bug: TrueType fonts in the header/footer are corrupted with Distiller 3.0. (Workaround: Change fonts or use Distiller 4.0 instead.)

                   Size   Date          Time
   mif.jar         31977  Jul 20, 1999  16:19 
   mifdoclet.jar   98971  Jul 20, 1999  16:19

• Known Bug: A space is missing between words. This occurs at the boundary of newlines in doc comments.
• Known Bug: When converted to PDF, links in the index appear in the white space to the right of the page number.
• Known Bug: OutlineHead style is white font; should be black.
• Known Bug: titlepage.mif was inadvertently omitted from the download bundle. You can get it from the MIF doclet home page. NOTE: This file contains a dummy copyright information on page 2. Be sure to modify this for your company.
• Known Bug: There are some content bugs not present in the standard doclet. Array brackets [] do not appear in the return type.
• Known Bug: {@link name label} tags display the name rather than the label.
• Known Bug: In Solaris, opening template and any generated MIF files produces warning that "Arial", "TimesNewRoman" and "TimesNewRoman Bold" fonts are not available.