MIF Doclet
for Generating FrameMaker and PDF Documents
Version 5 Beta 1
THIS DOCUMENT NOT YET UPDATED FOR VERSION 5 Beta 1
Need to integrate the following red text into the body of this document.
RED = Internal versions
Version 5 Beta 1 - Internal Build (build date: ??)
This upcoming (not-yet-released-to-public) version of the MIF Doclet is
compatible with the Javadoc tool found in JDK 5.0, but not earlier versions.
It works with FrameMaker 5.5, 6.0 or 7.0.
Running MIF Doclet
NOTE: This version is based on a copy of the new internal doclet toolkit
included in JDK 5.0. It uses the package name "com.sun.tools.doclets.internal.toolkit",
which does conflict with the JDK 5.0 package name of the
same name, and therefore must be used with "java" command to call javadoc Main,
and cannot work with the javadoc command.
NOTE: Starting with MIF Doclet version 1.4 Beta 1, the package name of the
MIF Doclet has changed, requiring the following change to the
-doclet option:
-doclet com.sun.tools.doclets.formats.mif.MIFDoclet
Because of the first note above, the MIF doclet must be called using java, not javadoc,
as follows:
java \
-classpath /home/dkramer/mif/jar/mifdoclet.jar:/programs/jdk1.5.0/lib/tools.jar \
-Xmx20M \
com.sun.tools.javadoc.Main \
-doclet com.sun.tools.doclets.formats.mif.MIFDoclet \
-book book.xml \
-sourcepath ./src \
com.package1
Bugs - For the most up-to-date lists of bugs, see:
Fixed
Not yet fixed
New Features and Changes - The following new features and
enhancements have been made:
- Displaying of generics and varargs in declarations
- Listing of enums and annotations in class lists
- {@inheritDoc} tag is supported - This feature has been
in the standard doclet for awhile and now works in this doclet.
- Custom tags and taglets are supported - This includes
the -tag and -taglet and -tagletpath options.
<OverviewFile> changed to
<Overview> - This change was
necessary in order to make the MIF doclet option consistent
with the standard doclet option. Likewise, the -overviewfile
option has been renamed -overview.
- Verbose by default - The
<Verbose> option
(including -verbose) is obsolete,
so please remove it from your XML book file.
The default is now to display verbose messages, which has been extended
to echo each statement in the batch processor as the files are converted
to FrameMaker and PDF. This should be a great help in bug tracking.
To counter this, we have added an option
<Quiet enabled="true"/> (or -quiet) to hide all
messages (which is not yet fully implemented).
- Static Field Constants and Serialized Form pages -
These pages are included by default when not using an XML book file.
The serialized form page can be suppressed using
-noserializedform
If using an XML book file, you must supply these options:
<Chapter>
<ConstantsFile> constant-values.mif </ConstantsFile>
</Chapter>
<Chapter>
<SerializedFormFile> serialized-form.mif </SerializedFormFile>
</Chapter>
- Chapter Auto-Numbering -
A new assignment
ChapterNumber.PgfNumFormat in the
stylemap.properties file can determine the chapter number format.
The following example sets the chapter numbers to use the C counter.
Notice that the right-angle-brackets need to be escaped with a backslash
(\>). See the FrameMaker documentation for details
about what all the terms following C: mean.
ChapterNumber.PgfNumFormat "C:<n+\>< =0\>< =0\>< =0\>< \>< \>< \>"
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 intend and have worked to make
it useful, bugs might not be fixed and features might not be added.
We reserve the right to release updates with an incompatible
implementation or page layout.
Reference Guide
Running
Customizing
Reference Guide
What is the MIF Doclet?
The MIF Doclet is an extension to the JavadocTM
tool that generates API documentation in MIF (Maker Interchange Format) from
declarations and doc comments in source code in the
JavaTM programming language.
It uses exactly the same set of
Javadoc
tags (such as @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:
- For a local copy: CHANGES
- For the most up-to-date version:
CHANGES (on http://java.sun.com)
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:
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
fmbatch or dzbatcher,
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
.java files) 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
(
fmbatch or dzbatcher) 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, @param and
@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.mif that you import.
As with the
standard
doclet, these auto-generated, internal links appear in many
places:
- "See Also" sections generated from
@see tags
- In-line text generated from
{@link} tags
- Exception names generated from
@throws tags
- "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
- 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 of doc-files directory)
to the destination fm/doc-files directory and imports
them by reference.
Any files in subdirectories of the original doc-files
are all moved directly into the destination doc-files
rather 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
@since tag
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
fmbatch or dzbatchers how 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:
- 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) or dzbatcher
(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.package1 and
com.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.fm at 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
450kB
|
|
Large 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
119MB
|
Testing 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
-link
and -linkoffline options 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.fm contains two pages:
a blank left-hand page followed by the almanac legend on a
right-hand page. The style AlmanacLegendHead
is 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.
MIF Doclet Command Syntax
The command syntax is basically the Javadoc syntax with -doclet
and -docletpath options and additional MIF doclet options.
javadoc -doclet com.sun.tools.doclets.mif.MIFDoclet \
-docletpath path/mifdoclet.jar \
[options] [packagenames] [sourcefiles] [@files]
See an example of the MIF doclet command.
Arguments can be in any order.
-
-doclet com.sun.tools.doclets.mif.MIFDoclet
- Specifies the fully-qualified name of the doclet class that
contains the
start method. In this case, this
is the MIFDoclet class.
-docletpath path/mifdoclet.jar
- Specifies the path and filename of the MIF doclet jar file.
The path separator is "
/" on Solaris and
"\" on Windows.
(If the class files are not in a jar file, this must
specify the path of the directory containing the class file
specified in the -doclet option.)
options
- Command-line options, as specified in this document.
packagenames
- A space-separated list of names of packages that you
want to document, such as
com.package1 com.package1.
You must explicitly specify each package you want to document.
Javadoc uses -sourcepath
to find these packages. Wildcards such as asterisks (*)
are not allowed -- the MIF doclet cannot recursively
traverse subpackages.
sourcefiles
- (Not implemented)
@files
- One or more files that contain any of the previous
arguments in any order.
MIF Doclet Options
You can access MIF Doclet options as command line options or as
XML Book File elements. When both are present, XML elements
override their command line option equivalents. Below are the lists
of the options (by name and by subject), followed by the alphabetic
detailed listing of all options and elements.
NOTE - You can also view lists of options in a separate HTML
frame along the left margin of this web page by choosing
FRAMES
at the top of this document. This makes it quite easy to move quickly
from option to option.
Command Line Options
- 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.
NOTE - The following command line options have no equivalent as
XML book options because they are implemented in the javadoc tool
and not in doclets: -bootclasspath, -classpath, -doclet,
-docletpath, -encoding, -extdirs, -help, -J, -locale, -package,
-private, -protected, -public, and -sourcepath.
These command line options have no equivalent, as explained in
their detailed description: -noalmanac, -nopackagepage.
XML Book File Elements
- 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.
Options - Listed by Name
A quicker way of accessing these options is to display the list in
the left-hand
frame.
Options shown in italic are the Javadoc core options,
which are provided by the front end of the Javadoc tool (and are
available to all doclets). The MIF doclet itself provides the
non-italic options.
Options - Listed by Subject
A quicker way of accessing these options is to display the list in
the left-hand
frame.
Options shown in italic are the Javadoc core options,
which are provided by the front end of the Javadoc tool (and are
available to all doclets). The MIF doclet itself provides the
non-italic options.
Option Details
The following section lists all MIF Doclet options alphabetically and
describes them in detail. Both the command line options and XML book
file options are described.
We've tried to stick to some guidelines when naming options.
A useful one is:
All options that take a filename as
an argument have names that end with "file".
These include -almanacfile, -batchmapfile,
-contentsfile, -indexfile,
-overviewfile, -stylemapfile,
-titlefile, and <SectionFile>.
Exception include -importformats and
-print.
- almanacfile
-almanacfile miffile | fmfile
|
|
(Command line) |
|
<AlmanacFile> miffile | fmfile </AlmanacFile>
|
|
(XML book file) |
|
-
The almanac is a concise listing of the API, with layout similar to
The Java Developers Almanac by Patrick Chan.
Each class and interface is listed with a class hierarchy diagram
and a list of each member's declaration. The
<AlmanacFile> tag can be positioned either as
a chapter or as a section in the back matter.
This option generates an almanac-formatted chapter or section,
inserting the file specified by miffile. Supplying the
default filename of almanac.mif or
almanac.fm causes the default, auto-generated
almanac to be generated. Supplying any other filename allows
you to supply your own almanac.
There are some differences depending on whether you supply
an XML book file when executing the MIF doclet:
You can substitute almanac.fm in any of the places
above where almanac.mif is used.
The almanac tables are mostly hard-coded into the MIF doclet.
They do not use the table definitions of AlmanacTable or
AlmanacTablehead in the template.
However, because the almanac tables are designed to fill the column
widths, you can adjust their widths with the
-columnwidth option.
Limitations - The current version has no option for either changing
the almanac chapter title or for adding text ahead of the API.
You can insert these by hand. Also note that, by design,
the list of members does not include nested classes (either static
or nonstatic). Also, while Patrick Chan's almanac includes
inherited members, this one does not.
Almanac Legend - The almanac contains some Zapf Dingbat
symbols that represent abstract, final, static, protected,
constructor and field. The almanac legend
(almanaclegend.mif) displays and describes
these symbols. This legend also identifies the class
name, package name, class hierarchy, inheritance chain,
implemented interfaces, @since comment, and return type.
This legend file is automatically copied from the resources
directory of mifdoclet.jar whenever the almanac is created.
- author
|
|
<Author enabled="true"|"false" />
|
|
(XML book file) |
|
-
Creates an "Author" subhead at the end of the class description,
followed by the text from the
@author tag. You can have
one or more @author tags. Example:
Author: Doug
This option is the same as the
-author option
in the Javadoc core options.
- backmatter
|
(No equivalent for command line)
|
|
|
|
<BackMatter> ... </BackMatter>
|
|
(XML book file) |
|
-
Defines the back part of the book -- from the end of the last chapter
to the end of the book. There is no action associated with this tag.
Page number continues in arabic style from the chapters part of the book.
This element is actually not necessary and can be omitted, as it performs no
action. This element is included to make the XML book file more
human-readable. This option has no command line equivalent.
- batch
-batch path/fmbatch | path/dzbatcher
|
|
(Command line) |
|
<Batch> path/fmbatch | path/dzbatcher </Batch>
|
|
(XML book file) |
|
-
NOTE - This option requires the program
fmbatch or
dzbatcher.
Creates the batch file mif-to-fm.batch, then uses
fmbatch or dzbatcher, as specified, to run it.
This option converts the MIF files to FrameMaker files, updates the page
numbers and cross-references, and generates the table of contents and index.
If this option is omitted, complete MIF files are generated, but no batch file is
created, and therefore the MIF files are not converted to FrameMaker files,
and none of the other operations just described are performed; the
table of contents and index files are created but are empty.
If its path is in your system's PATH setting, you can supply just
the batch program name without its path, such as:
-batch fmbatch
If the batch program cannot be found, you get an error like
"File not found." Or you can supply the full path with the argument.
Use the path separator appropriate to your operating system: backslash
(\) for Windows and forward slash (/) for Solaris:
-batch /usr/local/frame5.5.6/bin/fmbatch
For more information about the batch commands in mif-to-fm.batch,
see Install the batch program under setup.
NOTE - 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 (now -bookfilename.
Omitting -bookfile would prevent the FrameMaker files
from being generated. This dependency has been removed in this
version -- if -batch is supplied without
-bookfilename, it will create a FrameMaker book file
and generate the FrameMaker files.
Also see related option -noexecutebatch.
- batchfilepaths
-batchfilepaths absolute | relative
|
|
(Command line) |
|
<BatchFilePaths> absolute | relative <BatchFilePaths>
|
|
(XML book file) |
|
-
Sets the paths of files in the generated batch file
to
absolute (default) or relative.
Relative is useful when generating the MIF files (which
do not require the batch processor) on one machine and then
converting from MIF to FM on another machine. The default
is absolute because we have encountered a
bug, when using relative, with getting the
MIF doclet to properly call dzbatcher on Windows NT.
- batchmapfile
-batchmapfile file.map
|
|
(Command line) |
|
<BatchmapFile> file.map <BatchmapFile>
|
|
(XML book file) |
|
-
(Very rarely used.)
Specifies a file for mapping batch commands for use with a MIF batch
processor such as
fmbatch or dzbatcher.
The MIF doclet contains built-in versions of this file for these two
batch processors: fmbatch.map and dzbatcher.map
(located in the com/sun/tools/doclets/mif/resources directory
of the jar file). If you omit this option, the MIF Doclet uses the
built-in versions. You can also specify the built-in versions by
specifying the built-in filename with no path, such as:
-batchmapfile fmbatch.map
This option looks in the current directory from where the doclet was
started for a file of that name before using the default version.
If you copy the build-in file to the current directory, renamed it
myfmbatch.map, and modified it, you would call it as follows:
-batchmapfile ./myfmbatch.map
Supply a different file with the -batchmapfile option
only in the unlikely event that the mappings change or you are
using a third batch processor.
To illustrate the need for mapping, fmbatch and dzbatcher
accept different syntax for printing to a printer; fmbatch
takes:
Print file settingsfile
while dzbatcher takes:
Print -p settingsfile file
These commands are abstracted in fmbatch.map as:
PrintGeneric=Print $gen $settings
and in dzbatcher.map as:
PrintGeneric=Print -p $settings $gen
- book
-book xmlfile
|
|
(Command line) |
|
|
(No equivalent for XML book file)
|
|
(XML book file)
|
|
-
Names the XML book file (or subbook) to use. This file contains
XML elements that substitute for most of the command line options.
It also can specify the order of files to be generated.
See also XML Book File.
Example:
-book book.xml
For a full example, see XML book file
example.
For information on master book and subbook files, see
includebook.
- bookauthor
-bookauthor authorstring
|
|
(Command line) |
|
<BookAuthor> authorstring </BookAuthor>
|
|
(XML book file) |
|
-
Searches for all instances (normally one) of the string "
[BookAuthor]"
in the title file titlepage.fm and replaces each one with authorstring.
Used for specifying the name of the author or authors of the book being generated.
The authorstring can contain any of the FrameMaker
special characters. This option is a shortcut for
using replacetitlestr.
- bookcopyright
-bookcopyright copyrightstring
|
|
(Command line) |
|
<BookCopyright> copyrightstring </BookCopyright>
|
|
(XML book file) |
|
-
Searches for all instances (normally one) of the string "
[BookCopyright]"
in the title file titlepage.fm and replaces each one with copyrightstring.
Used for specifying the copyright statement for the book being generated.
The copyrightstring can contain any of the FrameMaker
special characters. This option is a shortcut for
using replacetitlestr.
- bookdedication
-bookdedication dedicationstring
|
|
(Command line) |
|
<BookDedication> dedicationstring </BookDedication>
|
|
(XML book file) |
|
-
NOTE - Because most API documents do not normally contain a dedication,
this option is different from all the other book* options
that replace strings in the title file: The string
"[BookDedication]" does not appear in the default
title file. To make this option work, you must add this string to the
title file (and use the titlefile
options). You would normally put the dedication on a new page.
This option searches for all instances (normally one) of the string
"[BookDedication]" in the title file titlepage.fm
and replaces each one with dedicationstring.
Used for specifying the names of those who the book is to be dedicated to.
The dedicationstring can contain any of the FrameMaker
special characters. This option is a shortcut for
using replacetitlestr.
- bookfilename
-bookfilename filename.book
|
|
(Command line) |
|
<BookFilename> filename.book </BookFilename>
|
|
(XML book file) |
|
-
Names the MIF book file with filename. (Also names the PDF file,
as described below.) It will not alter or add
an extension to the filename you supply. For example,
you can name it
myapi.book or myapibook
(with no extension). However, the common convention is to use the
.book extension.
If you omit this option, the Framemaker book file is named api.book.
This book file is a type of FrameMaker file that contains the filenames
of all the files in the book, including the title page, contents page,
overview page, package pages (if any), class pages, and index page.
Because the PDF filename is derived from by changing the .book
extension to .pdf, this option also renames the PDF file.
(Was named -bookfile in version C.)
- bookpublisher
-bookpublisher publisherstring
|
|
(Command line) |
|
<BookPublisher> publisherstring </BookPublisher>
|
|
(XML book file) |
|
-
Searches for all instances (normally one) of the string "
[BookPublisher]"
in the title file titlepage.fm and replaces each one with publisherstring.
Used for specifying the name of the publisher of the book being generated.
The publisherstring can contain any of the FrameMaker
special characters. This option is a shortcut for
using replacetitlestr.
- booksubtitle
-booksubtitle subtitlestring
|
|
(Command line) |
|
<BookSubTitle> subtitlestring </BookSubTitle>
|
|
(XML book file) |
|
-
Searches for all instances (normally one) of the string "
[BookSubTitle]"
in the title file titlepage.fm and replaces each one with subtitlestring.
Used for specifying the name of the subtitle of the book being generated.
The subtitlestring can contain any of the FrameMaker
special characters. This option is a shortcut for
using replacetitlestr.
- booktitle
-booktitle titlestring
|
|
(Command line) |
|
<BookTitle> titlestring </BookTitle>
|
|
(XML book file) |
|
-
Searches for all instances (normally one) of the string "
[BookTitle]"
in the title file titlepage.fm and replaces each one with titlestring.
Used for specifying the name of the title of the book being generated.
The titlestring can contain any of the FrameMaker
special characters. This option is a shortcut for
using replacetitlestr.
- bookversion
-bookversion versionstring
|
|
(Command line) |
|
<BookVersion> versionstring </BookVersion>
|
|
(XML book file) |
|
-
Searches for all instances (normally one) of the string "
[BookVersion]"
in the title file titlepage.fm and replaces each one with versionstring.
Used for specifying the name of the version of the API or book being generated.
The versionstring can contain any of the FrameMaker
special characters. This option is a shortcut for
using replacetitlestr.
- bootclasspath
-bootclasspath pathlist
|
|
(Command line) |
|
|
(No equivalent for XML book file)
|
|
|
|
-
Overrides location of class files loaded
by the bootstrap class loader.
This option is identical to the
-bootclasspath option
in the Javadoc core options.
- chapter
|
(No equivalent for command line)
|
|
|
|
<Chapter> ... </Chapter>
|
|
(XML book file) |
|
-
Defines a chapter. The first chapter resets the page numbers to
page 1, Arabic style. Chapters also can have chapter numbers, as defined
by
<ChapterNumbering>.
This option has no command line equivalent.
- chapternumbering
-chapternumbering
|
|
(Command line) |
|
<ChapterNumbering enabled="true"|"false" />
|
|
(XML book file) |
|
-
Turns chapter numbering on by generating a paragraph containing the
chapter string, and applying the FrameMaker
style
ChapterNumber to that paragraph. The
ChapterNumber style definition provides the chapter number.
When enabled is set false, the paragraph is
not generated (and chapter string and number are thereby ignored).
When using the -chapternumbering command line option,
each new package starts a new chapter. (This is similar to using an
XML book file and specifying a new chapter with the
<Chapter> tag.)
- chapters
|
(No equivalent for command line)
|
|
|
|
<Chapters> ... </Chapters>
|
|
(XML book file) |
|
-
Defines the part of the book where the chapters are included. The only
action is that the page numbers are reset to page 1, Arabic style,
at the start of this section.
These tags are actually not necessary -- if omitted, the first
<Chapter> element is
interpreted as the end of the front matter and start of the first chapter.
This element is included primarily to make the XML book file more human-readable.
This option has no command line equivalent.
- chapterstring
-chapterstring string
|
|
(Command line) |
|
<ChapterString> string </ChapterString>
|
|
(XML book file) |
|
-
Inserts string ahead of the chapter number at the top of a
chapter file. A typical use (in English) is:
-chapterstring "\r\rCHAPTER\s"
The special characters \r\r insert two new lines above the
string as part of the same paragraph. This moves this paragraph (and
subsequent paragraphs) vertically down the page, to provide some blank space at
the top of the first page of each chapter. This blank space is needed to
make room for the chapter number in the default template, which is much taller
than the string "CHAPTER". The \s inserts a space
after the string, before the page number.
- class
|
(No equivalent for command line)
|
|
|
|
<Class> classname </Class>
|
|
(XML book file) |
|
-
Generates and inserts the class page for the specified
classname. This option has no command line equivalent.
Example:
<Class> java.lang.Object </Class>
- classpath
-classpath pathlist
|
|
(Command line) |
|
|
(No equivalent for XML book file)
|
|
|
|
-
Specifies where to find user class files.
This option is identical to the
-classpath option
in the Javadoc core options.
- columnwidth
-columnwidth width | default
|
|
(Command line) |
|
<ColumnWidth> width | default </ColumnWidth>
|
|
(XML book file) |
|
-
This option is used to set the width of MIF tables that are
generated from HTML tables whose width is expressed
as a percentage of the browser window's width. An HTML table of width 100% converts
to a MIF table whose width is width. Specify for width the width of
the text column in your template using any of the dimensions shown in the
table below. If this option is omitted,
or if a value of
default is used, the column width is 470 points,
which is designed for the default 8.5 x 11" template.mif.
This applies not only to doc comment tables that are supplied by the user,
but also to summary tables for packages, classes and members that are synthesized
by the doclet. It does not apply to HTML tables whose width is specified as a
fixed dimension rather than a percentage. You'll notice if you create a custom
template that changes the width of the text column from the default of 470pt,
you will need to use this option to correspondingly change the width of the tables.
For example, if an HTML table has a width specified as follows; notice
percentages must be used in both the TABLE and TD tags:
<TABLE WIDTH="100%">
<TR>
<TD WIDTH="40%">
First column.
</TD>
<TD WIDTH="60%">
Second column.
</TD>
</TR>
</TABLE>
the following option would cause the corresponding MIF table to have an
overall width of 4.5 inches:
-columnwidth 4.5in
In the future we might require a percentage appear only in the TABLE tag
and not in the TD tags.
A proportionally larger or smaller percentage would set the
table wider or narrower. Specifically, an HTML table set to
<TABLE WIDTH=n%>
would have its width in the MIF document set to
n% x width.
For example, with <TABLE WIDTH=80%> and
-columnwidth 4.5in, the MIF table width would
be set to 80% x 4.5 inches = 3.6 inches.
This option is named "columnwidth" because a value of 100% corresponds
to the width of the text column.
Notice that the FrameMaker template's master pages define the actual
width of the text column -- this option does not set the width
of the master page column.
In the future, this option may also apply to images and horizontal
rules with widths specified as percentages, when those features
are supported by the MIF doclet.
Table width dimensions - Acceptable units for width
are points, inches, picas, centimeters, and millimeters,
which can be entered shown in the following table. All the values shown
below are approximately equivalent -- that is, 328 points =
4.5 inches = 27 picas = 11.43 centimeters = 114.3 millimeters.
The dimensions can be entered in uppercase, lowercase or mixed case.
You can put a space between the value and dimension, but then must enclose
them both in quotes, such as "328 points".
| width | Meaning |
328
328pt
328point
328points | 328 points |
4.5i
4.5in
4.5inch
4.5inches
| 4.5 inches |
27pi
27pc
27pica
27picas | 27 picas |
11.43c
11.43cm | 11.43 centimeters |
114.3m
114.3mm | 114.3 millimeters |
Also see -summarytablefirstcolumn.
- combineoverloads
-combineoverloads
|
|
(Command line) |
|
<CombineOverloads enabled="true"|"false" />
|
|
(XML book file) |
|
- Combines declarations and documentation for method overloads under a single
heading. The declarations and documentation for each overload is appended
under the heading.
Also sets
memberhead to noargs, since that is the
appropriate heading. For example, the overloaded methods getImage(URL)
and getImage(URL, String) in java.applet.Applet would
appear as shown in the following example. Notice there may be redundancy. You
may want to re-write doc comments to eliminate redundancy.
- getImage
public java.awt.Image getImage(java.net.URL url)
- Returns an
Image object that can then be painted on
the screen. The url that is passed as an argument
must specify an absolute URL.
-
- Parameters:
url - an absolute URL giving the location of the image.
- Returns:
- the image at the specified URL.
- See Also:
Image
public java.awt.Image getImage(java.net.URL url,
java.lang.String name)
- Returns an
Image object that can then be painted on
the screen. The url argument must specify an absolute
URL. The name argument is a specifier that is
relative to the url argument.
-
- Parameters:
url - an absolute URL giving the base location of the image.
name - the location of the image, relative to the
url argument.
- Returns:
- the image at the specified URL.
- See Also:
Image
|
- constantvaluespage
constantsfile
-constantvaluespage
|
|
(Command line) |
|
<ConstantsFile> constant-values.mif </ConstantsFile>
|
|
(XML book file) |
|
-
Generates a section with a list of values for the static constant
fields in the classes and interfaces being documented. It also
inserts a link at the detailed description of each static
constant field, so someone reading the field description can
follow the link to the field's value in this list.
For an example of <ConstantsFile>, see
XML Book File example.
Notice the command line option and xml book file options have different
names and arguments. In both cases, the option must be included for
the constants page to appear. The -constantsvaluespage
option will disappear in a later version of the MIF Doclet, when the
constants page will be generated by default from the command line.
Default Constants File -
To generate the default constants page, pass in constant-values.mif
or constants.fm:
<ConstantsFile> constant-values.mif </ConstantsFile>
Results: In this case, the doclet copies the resource file
constant-values.mif from mifdoclet.jar
to the mif (or fm) destination directory and imports formats from
template.mif.
Custom Constants File -
You can modify the main heading, formatting and layout of
the table of constants. The file should be empty except for
any static text you want to appear in the finished file.
It should have whatever style definitions the table of
constants needs, as the doclet will not import a template
into this file. To supply this file, you pass in its path
and filename, for example:
<ConstantsFile> myconstant-values.mif </ConstantsFile>
You can precede the specified file by a path that is absolute, or is
relative to the current directory from where the MIF doclet is started.
If you want to use the default name and keep it in the current
directory, you can do so by prefixing it with the current directory:
<ConstantsFile> ./constant-values.mif </ConstantsFile>
Results: When specifying a custom constants file, the doclet copies the
specified constants page file to the mif (or fm) destination
directory and includes it in the generated FrameMaker book file
as a .fm file. (If the file is not found,
the MIF Doclet prints a warning and continues.)
The doclet does not import formats into that file,
even if -importformats is specified.
This enables you to modify that custom file without regard
to the styles in the imported template.
- contentsfile
-contentsfile miffile | fmfile
|
|
(Command line) |
|
<ContentsFile> miffile | fmfile </ContentsFile>
|
|
(XML book file) |
|
-
Use this option to specify the file used for the table of contents
page.
Default Contents File -
To generate the default contents page, pass in contents.mif
or contents.fm:
<ContentsFile> contents.mif </ContentsFile>
Results: In this case, the doclet copies the resource file
contents.mif from mifdoclet.jar
to the mif (or fm) destination directory and imports formats from
template-roman.mif.
Custom Contents File -
You can modify the main heading, formatting and layout of
the table of contents. The file should be empty except for
any static text you want to appear in the finished file.
It should have whatever style definitions the table of
contents needs, as the doclet will not import a template
into this file. To supply this file, you pass in its path
and filename, for example:
<ContentsFile> mycontents.mif </ContentsFile>
You can precede the specified file by a path that is absolute, or is
relative to the current directory from where the MIF doclet is started.
If you want to use the default name and keep it in the current
directory, you can do so by prefixing it with the current directory:
<ContentsFile> ./contents.mif </ContentsFile>
Results: When specifying a custom contents file, the doclet copies the
specified contents page file to the mif (or fm) destination
directory and includes it in the generated FrameMaker book file
as a .fm file. (If the file is not found,
the MIF Doclet prints a warning and continues.)
The doclet does not import formats into that file,
even if -importformats is specified.
This enables you to modify that custom file without regard
to the styles in the imported template.
Contents styles -
This option builds the contents from the following paragraph
styles that are currently hard-coded into the MIF doclet:
SectionHead
OverviewHead
PackageHead
ClassHead
ChapterHead
AlmanacHead
IndexHead
Setting up the custom contents file - Apply the master page on
the first page of this custom contents file as you would like the
first page to end up (the name of this first master page can be any
name you want). Set up the master pages named "Left" and "Right"
to have the layout you want for the subsequent contents pages.
Set the page number style to arabic (1, 2, ...) or roman numeral
(i, ii, ...). If this is the first file in the book, this
style will determine how the page number style of the front matter.
Command line note -
If you are running the MIF doclet strictly from a command on
the command line to (and not calling an XML book file),
the contents page file is generated by default even
when this option is omitted from the command line.
- d
-d directory
|
|
(Command line) |
|
<D> directory </D>
| |
(XML book file) | |
|
-
The elements
<D> and <Destination>
are synonyms. This option sets the destination directory for the
generated files. If the argument is not an absolute path, it is
relative to the current directory from where the doclet is started.
The argument directory can contain spaces except if using
dzbatcher, which contains a bug that does not allow spaces.
The fmbatch program does support spaces in filenames.
The MIF Doclet creates directory if it doesn't exist.
It also creates subdirectories named mif,
fm and pdf to hold the MIF, FrameMaker
and PDF files, respectively.
- declarationhead
-declarationhead "class member" | cm | all | none
|
|
(Command line) |
|
<DeclarationHead> "class member" | cm | all | none </DeclarationHead>
|
|
(XML book file) |
|
-
Generates the word "Declaration" as a heading before the declaration
statement in the specified sections. Note that this option takes only
a single argument, which can be a string with any combination of
the words
class or member,
any combination of the letters cm, or the word
all (which means generate both class and member headings),
or none (which means generate no headings). The default
argument is class. These options are a subset of those
shown above in -descriptionhead.
- descriptionhead
-descriptionhead "overview package class member" | opcm | all | none |
|
(Command line) |
|
<DescriptionHead> "overview package class member" | opcm | all | none </DescriptionHead>
|
|
(XML book file) |
|
-
Generates the word "Description" as a heading before the description
text in the specified sections. Note that this option takes only
a single argument, which can be a string with any combination of
the words
overview, package, class,
and member,
any combination of the letters opcm, or the word
all (which means generate all four headings), or none
(which means generate no headings). The default is overview
package class.
o or overview | Overview page |
p or package | Package page |
c or class | Class page |
m or member | Member section |
For example, using "-descriptionhead class" for
the java.applet package would cause the heading "Description" to appear
before its class description, like this:
Description
Provides the classes necessary to create an applet and the classes
an applet uses to communicate with its applet context.
- destination
|
(No equivalent for command line)
|
|
|
|
<Destination> directory </Destination>
|
|
(XML book file) |
|
-
Synonym for
<D>, listed above.
- doclet
-doclet class
|
|
(Command line) |
|
|
(No equivalent for XML book file)
|
|
|
|
-
Specifies the starting class for the doclet, using the fully-qualified
name. For the MIF doclet, use:
-doclet com.sun.tools.doclets.mif.MIFDoclet
This option is identical to the
-doclet option
in the Javadoc core options.
- docletpath
-docletpath path/mifdoclet.jar
|
|
(Command line) |
|
|
(No equivalent for XML book file)
|
|
|
|
- Specifies the path and filename of the MIF doclet jar file.
The path can be either absolute or relative to the current
directory from where the doclet is run. The path separator
is "
/" on Solaris and "\" on Windows.
An example of -docletpath is shown in the
minimal example.
This is all you need to know for the standard implementation
of the MIF Doclet. If you are modifying the MIF doclet
to rely on other jar files, you might need the more general
form:
-docletpath docletpathlist
where docletpathlist specifies the path and filename of
the doclet jar file plus any jar files it depends on.
If the class files are not in a jar file, instead specify
the path of the directory containing the class file
specified in the -doclet option.
If docletpathlist contains multiple paths, they
should be separated with a colon (:) on Solaris
and a semicolon (;) on Windows.
This option is identical to the
-docletpath option
in the Javadoc core options.
- encoding
-encoding name
|
|
(Command line) |
|
|
(No equivalent for XML book file)
|
|
|
|
-
Specifies encoding name of the source files.
This option is identical to the
-encoding option
in the Javadoc core options.
- excludeclasses
-excludeclasses class1:class2:...
|
|
(Command line) |
|
<ExcludeClasses> class1:class2:... </ExcludeClasses>
|
|
(XML book file) |
|
-
Specifies the classes to be excluded from the documentation, where class1:class2... are fully-qualified class names. For example:
-excludeclasses java.applet.AppletStub:java.applet.AudioClip
This causes the corresponding class pages to be omitted from the
documentation, and these class names to be omitted from the Class
Summary for their packages.
- extdirs
-extdirs dirlist
|
|
(Command line) |
|
|
(No equivalent for XML book file)
|
|
|
|
-
Overrides location of installed extensions.
This option is identical to the
-extdirs option
in the Javadoc core options.
- frontmatter
|
(No equivalent for command line)
|
|
|
|
<FrontMatter> ... </FrontMatter>
|
|
(XML book file) |
|
-
Defines the front part of the book -- from the title page up to where
the first chapter begins. The action is that the page numbers start with
page 1, Roman numeral style, starting at the first page in the book
(normally the title page). This element is actually not necessary --
if omitted, any elements ahead of the first
<Chapter> element
are interpreted as the front matter. This element is included to make the
XML book file more human-readable. This option has no command line equivalent.
- group
-group groupheading pkgpattern1:pkgpattern2...
|
(Command line) |
|
<Group> groupheading pkg1:pkg2... </Group>
|
|
(XML book file) |
|
-
Groups packages together in a table on the overview page as described in the
standard
doclet. You can supply a different group option for each set of packages
you want to group. If you omit this option, all packages appear in a single
group named "Package Summary".
Important Restriction - Notice in the syntax above that that the
-group option takes a wildcard pattern while the
<Group> option does not. In other words, the former
can take the wildcard '*' character, while the latter takes only an
explicit list of package names.
(If you supply a wildcard with <Group>, it is treated
as an illegal package name and none of the packages will match -- they
will instead appear under the heading "Other Packages".) For this reason,
we use -group in the
XML book file example.
The following example groups all java.lang* packages (which
includes java.lang and java.lang.reflect) with the
java.util package under the heading "Core Packages".
(Notice that the period must be omitted following "lang" in
"java.lang*" because "java.lang.*" would not match
on the java.lang package.)
-group "Core Packages" "java.lang*:java.util"
-group "Applet Packages" "java.applet"
This example is equivalent to the previous one. The packages
java.lang and java.lang.reflect must both be
explicitly called out here.
<Group> "Core Packages" "java.lang:java.lang.reflect:java.util" </Group>
<Group> "Applet Packages" "java.applet" </Group>
- help
|
|
|
(No equivalent for XML book file)
|
|
|
|
-
Displays these command line options.
- hrefdocroot
-hrefdocroot extdocURL
|
(Command line) |
|
<HRefDocRoot> extdocURL </HRefDocRoot>
|
|
(XML book file) |
|
- Specifies the URL to prepend to relative hypertext links in
<A HREF="URL"> .
The argument extdocURL must be an absolute URL.
If this option is omitted, then don't display the references for relative links.
Use this option when specifying a relative <A HREF>
link in a doc comment, such as:
/**
* This is a <a href="../dir1/com.test">label</a> to display.
*/
If you omit the -hrefdocroot option, the following is generated:
This is a label to display.
If you use this option with the following argument:
-hrefdocroot "http://java.sun.com/api"
Then when the MIF doclet encounters the above doc comment on the
overview.html page, it would prepend the -hrefdocroot
argument to the <A HREF> argument as follows:
This is a label (http://java.sun.com/api/../dir1/com.test) to display.
This option automatically includes the path necessary to reach
classes. For example, if the exact same doc comment appeared
in the source file for com.package1.Class1, it would generate as
as:
This is a label (http://java.sun.com/api/com/package1/../dir1/com.test) to display.
- imageresolution
-imageresolution value%
|
(Command line) |
|
<ImageResolution> value% </ImageResolution>
|
|
(XML book file) |
|
- Specifies the amount (in percent) to scale explicitly-sized images.
An image has an explicit size if it is defined by an <IMG> tag with
width and height parameters. It has no
effect on images that are missing those parameters. The default value
is 100%
Example:
-imageresolution 60%
This reduces the size of images to 30% of their size determined by
width and height parameters. For example, it reduces
the size of this image:
<IMG src ="myimage.gif" width=100 height=50>
to a width of 60 and height of 30 pixels.
- importformats
-importformats miffile | fmfile
|
(Command line) |
|
<ImportFormats> miffile | fmfile </ImportFormats>
|
|
(XML book file) |
|
-
Imports formats from the specified miffile or
fmfile template into all files generated by the
MIF doclet (with the following noted exceptions).
If omitted, the doclet imports formats from the
default template
template.mif. The exceptions
include any custom title page (-titlefile),
custom table of contents (-contentsfile),
and custom index (-indexfile). (The content
of these custom files is updated by the MIF Doclet, but they
are not formatted by it.)
Default template -
To use the default template page, either omit this option
altogether, or pass in the string template.mif:
-importformats template.mif
Results: The doclet extracts template.mif from
mifdoclet.jar and copies it to the mif
(or fm) destination directory and imports formats from it.
Custom template -
To supply a custom template, pass in its path and filename, where
the path either is absolute, or is relative to the directory from
where the MIF Doclet is started. For example, if
mytemplate.mif is in the current directory, use:
-importformats ./mytemplate.mif
If the template is in a directory templatedir
below the current directory and is saved as a FrameMaker
file to mytemplate.fm, use:
-importformats ./templatedir/mytemplate.fm
If you want to use the default name template.mif
for your custom template and keep it in the current directory,
you must prefix it with the current directory path
(.), or it will use the default template:
-importformats ./template.mif
Results: In these cases, the doclet copies the custom template
to the mif (or fm)
destination directory and imports formats from it. Only when
using a custom template, it prints a message in the form
"Saving mytemplate.mif as /home/user/docs/mif/mytemplate.mif".
How importing templates works -
Except for the files noted previously, the files that the
MIF Doclet generates are initially devoid of style definitions,
master pages, reference pages, and other formatting.
When this option is used, the MIF Doclet must get all
such formatting from the default or custom template. This option
is roughly functionally equivalent in FrameMaker to manually
choosing File > Import > Formats from the
menu.
If the MIF Doclet has trouble parsing the imported file (due to
internal operations), it prints a
warning and starts over with the default template. This is important
to note, as it may cause unexpected results.
You use this option to customize the FrameMaker styles, page layouts,
formats, definitions and setups. You can copy, rename and modify
template.mif and then pass the modified version in to
-importformats to override the default template.
Alternatively, you can pass in a pre-existing template, such as one
your company has set up, or create your own template in FrameMaker
(though that is not guaranteed
to work).
Note that the -importformats option, while conceptually
similar to the Import > Formats menu command in
FrameMaker, is quite different. With -importformats,
the imported template is broken up and inserted into the output
stream (generated files) as required, and has search and
replace performed on it for various purposes. For more details, see
Custom FrameMaker Templates.
NOTE - In FrameMaker if you open the MIF version
of the title, contents or index file, you will notice
that the styles have not been imported. This importing does
not occur for these files until they are converted to FrameMaker.
The other generated files have styles imported into the MIF
files.
- includebook
|
(No equivalent for command line)
|
|
(Command line) |
|
<IncludeBook> xmlfile </IncludeBook>
|
|
(XML book file)
|
|
-
Names the master XML book file to include in the current XML book file.
This normally goes at the top of the subbook file (after
<Book>
but before <Options> or <FrontMatter>).
When the doclet runs, the included file expands into the subbook file
at the location of the <IncludeBook> tag. You can view
the result of the expanded book file by looking at the
snapshot of the book file, which is helpful both
for history tracking and for troubleshooting.
Typically, the master book file contains the options and the subbook
contains the filenames in the order you want them printed, with some
overriding options. Also see -book and
XML Book File.
Example:
<IncludeBook> masterbook.xml </IncludeBook>
For a full example, see XML
master/subbook file example.
- indexfile
-indexfile miffile | fmfile
|
|
(Command line) |
|
<IndexFile> miffile | fmfile </IndexFile>
|
|
(XML book file) |
|
-
Use this option to specify the file used for the index
page.
Default Index File -
To generate the default index page, pass in index.mif
or index.fm:
<IndexFile> index.mif </IndexFile>
Results: In this case, the doclet copies the resource file
index.mif from mifdoclet.jar
to the mif (or fm) destination directory and imports formats from
template-roman.mif.
Custom Index File -
You can modify the main heading, formatting and layout of
the index file. The file should be empty except for
any static text you want to appear in the finished file.
It should have whatever style definitions the index needs,
as the doclet will not import a template into this file.
To supply this file, you pass in its path and filename,
for example:
<IndexFile> myindex.mif </IndexFile>
You can precede the specified file by a path that is absolute, or is
relative to the current directory from where the MIF doclet is
started. If you want to use the default name and keep it in the
current directory, you can do so by prefixing it with the current
directory:
<IndexFile> ./index.mif </IndexFile>
Results: When specifying a custom index file, the doclet copies the
specified index page file to the mif (or fm) destination
directory and includes it in the generated FrameMaker book file
as a .fm file. (If the file is not found,
the MIF Doclet prints a warning and continues.)
The doclet does not import formats into that file,
even if -importformats is specified.
This enables you to modify that custom file without regard
to the styles in the imported template.
This option builds the index from markers of type
Index.
NOTE - In the table of contents, the hyperlinks are on the text
and not the page numbers, while in the index, the reverse
is the case -- hyperlinks are on the page numbers, not the text.
This is because each table of contents entry links to a single
page, while a single index entry can link to multiple pages --
each one needs its own link.
Setting up the custom index file - Apply the master page on
the first page of this custom index file as you would like the
first page to end up (the name of this first master page can be any
name you want). Set up the master pages named "Left" and "Right"
to have the layout you want for the subsequent index pages.
Set the page number style to arabic (1, 2, ...) or roman numeral
(i, ii, ...). If this is the first file in the book, this
style will determine how the page number style of the front matter.
Command Line Note -
If you are running the MIF doclet strictly from a command on
the command line to (and not calling an XML book file),
the index page file is generated by default even
when this option is omitted from the command line.
- indexonecolumn
-indexonecolumn
|
(Command line) |
|
<IndexOneColumn enabled="true"|"false" />
|
|
(XML book file) |
|
-
Specifies that the alphabetic index (
index.mif) be
formatted in one column rather than the default two columns.
- indexstyle
-indexstyle hier | flat | brief
|
(Command line) |
|
<IndexStyle> hier | flat | brief </IndexStyle>
|
|
(XML book file) |
|
-
Specifies one of three styles for entries in the alphabetic index:
verbose with hierarchical indentation (
hier), verbose on one line
(flat), or simplified (brief).
The default is hier. (This option was named -index
in previous beta versions.)
The hier argument places the indexed term in bold at the first level,
and indents the class or package where it can found at the second level.
Grouping under a first level heading occurs. For example, methods with
identical signatures are grouped together, as shown with
getAppletContext(). The constructors are included in this index.
Here is an example:
-indexstyle hier
- Applet
- of java.applet 8
- Applet()
- of java.applet.Applet 10
- appletResize(int, int)
- of java.applet.AppletStub 23
- getAppletContext()
- of java.applet.Applet 9
- of java.applet.AppletStub 22
- resize(Dimension)
- of java.applet.Applet 11
- showDocument(URL, String)
- of java.applet.AppletContext 17
The brief argument is useful for reducing the clutter in the index
for packages that don't have a lot of method overloads -- for each entry
it omits the method parameters, parentheses and names of the packages they belong to.
It also omits constructor names from the index, since without the parentheses
they are indistinguishable from the class names, and because constructors
usually fall on the same page as the class. Here is the same example:
-indexstyle brief
Applet 8
appletResize 23
getAppletContext 9, 22
resize 11
showDocument 17
The flat argument might be used in a single-column format
(using -indexonecolumn), where
the page has more horizontal space. The constructors are included.
The text is printed entirely bold. You can redefine FrameMaker style
Level1IX in the template to be regular (not bold) to eliminate the bold.
Here is the same example again:
-indexstyle flat
Applet - of java.applet 8
Applet() - of java.applet.Applet 10
appletResize(int, int) - of java.applet.AppletStub 23
getAppletContext() - of java.applet.Applet 9
getAppletContext() - of java.applet.AppletStub 22
resize(Dimension) - of java.applet.Applet 11
showDocument(URL, String) - of java.applet.AppletContext 17
- insertapidoc
|
(No equivalent for command line)
|
|
|
|
<InsertAPIDoc> packages classes </InsertAPIDoc>
|
|
(XML book file) |
|
-
This option can be used only in the XML book file. It causes the
documentation for all packages and classes that are listed on the command
line to be inserted into the documentation in alphabetic order.
You can arrange them either split by classes or
packages. Include the argument
packages to
include the package pages and classes to
include the class pages. Include this element in a
<Chapters> element. Do not include this option
in a <Chapter> element, as this option automatically
determines the chapter breaks based on whether you are splitting by
package or class. This option has no command line equivalent.
This command can appear three ways.
- Include both package and class documentation:
<InsertAPIDoc> packages classes </InsertAPIDoc>
- Include only package documentation:
<InsertAPIDoc> packages </InsertAPIDoc>
- Include only class documentation:
<InsertAPIDoc> classes </InsertAPIDoc>
Omitting this option from the XML book file causes no packages or
class documentation to be included unless <Package> or
<Class> is used.
There is no command line option for this feature, because the
MIF doclet includes all packages and classes listed on the command
line when an XML book file is not used.
See XML Book File - Chapters for
how to use this option.
- inter
|
(No equivalent for command line)
|
|
|
|
<Inter> interfacename </Inter>
|
|
(XML book file) |
|
-
Synonym for
<Interface>.
- interface
|
(No equivalent for command line)
|
|
|
|
<Interface> interfacename </Interface>
|
|
(XML book file) |
|
-
Generates and inserts the interface page for the specified
interfacename.
Note that
<Interface> and <Inter>
are synonyms. The shorter element name is the same length as
<Class> and so makes a mixed column of class
and interface names easier to read. This option has no command line
equivalent. Examples:
<Interface> java.applet.AppletContext </Interface>
<Inter> java.applet.AppletContext </Inter>
- J
|
|
|
(No equivalent for XML book file)
|
|
|
|
-
Passes flag directly to the Java runtime environment.h
For example:
-J-Xms10M
- Sets the starting (
ms) amount of memory
to 10MB (the default is 2MB)
-J-Xmx100M
- Sets the maximum (
mx)
amount of allocated memory to 100MB (the default is 64MB).
You can use either uppercase "M" or lowercase "m"
to indicate megabytes. The doclet will print an "out of memory"
message to let you know the second of the two values needs to be set
higher.
This option is identical to the
-J option
in the Javadoc core options.
- link
-link path
|
|
(Command line) |
|
<Link> path </Link>
|
|
(XML book file) |
|
-
NOTE - In practice, this option is currently unusable, due to the
following restrictions. It may be fixed in a later release.
Creates links for external referenced classes to documentation
located at path. These external classes are referenced
in the generated documentatation but their documentation is not
being generated during this Javadoc run.
The MIF doclet determines which packages are at location path
by the contents of the package-list file at that
location. For more details, see
-link
in the standard doclet.
Example and current restrictions -
As an example, suppose directory /home/java/lang/fm
contains FrameMaker docs for package java.lang.
When generating docs for another package, say java.io,
you could use:
-link /home/java/lang/fm
to create links in the new java.io FrameMaker docs
pointing to classes in the existing java.lang
FrameMaker docs.
How it works: The MIF doclet searches the directory
/home/lang/fm for file package-list.
From that list, the doclet will know which packages in the external
docs can be referenced in the docs being generated. Whenever
an external package is referenced, a link is created to the appropriate
file.
Restrictions:
- Links currently work only between FrameMaker files.
Links cannot be created to or from HTML or PDF documents.
- Each link displays a page number, but this is a page number
in another book, which is confusing.
- Links work only if passing in an absolute path for
-link.
This means documents are not particularly portable to other
file systems.
- The
-link option works only with file paths,
not "http:" or "file:" URLs.
- The
-linkoffline option works only if both arguments
are identical, which reduces it to be equivalent to the
-link option.
- linkoffline
-linkoffline path1 path2
|
|
(Command line) |
|
<LinkOffline> path1 path2 </LinkOffline>
|
|
(XML book file) |
|
-
NOTE - In practice, this option is currently unusable, due to the
restrictions described in -link (above).
It may be fixed in a later release.
Creates links to documents at path1 using the package list
file at path2. For more information about a package list, see
-linkoffline option for the standard doclet.
Note that these are paths, not URLs. In the current release,
path1 and path2 must point to the same directory.
- locale
-locale name
|
|
(Command line) |
|
|
(No equivalent for XML book file)
|
|
|
|
-
Specifies locales to be used, such as
en_US or en_US_WIN.
This option is identical to the
-locale option
in the Javadoc core options.
- memberhead
-memberhead args | noargs | declaration
|
|
(Command line) |
|
<MemberHead> args | noargs | declaration </MemberHead>
|
|
(XML book file) |
|
-
Generates one of three heading styles for fields, methods
and constructors, shown below. If this option is omitted,
args is the default.
args
-
Generates member headings with argument types (but not argument
names) shown in parentheses. For example:
- getImage(URL)
public java.awt.Image getImage(java.net.URL url)
Returns an Image object that can then be painted on the screen.
noargs
-
Generates shorter member headings by omitting the parentheses and
arguments from methods and constructors. Note that this causes
overloaded methods to have the same heading, which can be confusing.
Therefore, use
noargs when the documented code has
no overloaded methods. This option is automatically used with the
-combineoverloads
option. The previous example would have this heading:
- getImage
public java.awt.Image getImage(java.net.URL url)
Returns an Image object that can then be painted on the screen.
declaration
-
Uses the declaration for the member heading. This includes
access modifier, return type, member name, argument types and
argument names.
This saves vertical space because it combines two lines
(heading and and signature) into one. (In this case,
the heading is given the FrameMaker style
MemberHeadDeclaration.)
For example:
public java.awt.Image getImage(java.net.URL url)
- Returns an Image object that can then be painted on the screen.
Important - Due to a constraint in FrameMaker, this declaration
appears as the link's label in every auto-generated
internal cross-reference link in your document. You might find
this unacceptable. (The FrameMaker constraint is that FrameMaker
cross-reference links appear exactly the same as the text they refer
to.)
As a consequence, you should use declaration only with
-membersummary none, because
in the member summary tables for constructors, methods and fields (but not
nested classes), the modifiers are confusingly repeated in the first
and second columns.
public static void public static void main(java.lang.String[] args)
This might not be a problem because someone trying to save space
using declaration might not want to waste space by including
a summary table. (If you need the summary table to appear, let us know --
we could modify the MIF Doclet to remove the first column for members
other than nested classes.)
- membersummary
-membersummary full | compact | none
|
|
(Command line) |
|
<MemberSummary> full | compact | none </MemberSummary>
|
|
(XML book file) |
|
-
Generates the full, compact or no member summary.
full - Includes return type, some modifiers, the member
name member arguments, and the first sentence of the description.
This is the default.
compact - Same as full but omits the
first sentence, and is therefore briefer.
none - Omits the entire Member Summary table.
- noalmanac
-noalmanac
|
|
(Command line) |
|
|
(No equivalent for XML book file)
|
|
|
|
-
Suppresses the generation of the almanac. See
-almanacfile for more information.
This option has no XML book file element equivalent. To omit the almanac
when using an XML book file, simply omit the <Almanac>
element.
- noclassprehead
-noclassprehead
|
|
(Command line) |
|
<NoClassPreHead enabled="true"|"false" />
|
|
(XML book file) |
|
-
Do not generate the package name before the class heading at the top
of each class page (
enabled="true"). When set
false (or when the command line option is omitted),
the package name appears before the class name -- for the Applet
class in the java.applet package:
java.applet
Applet
Setting this option true would cause the package name
"java.applet" to be omitted:
S
Applet
- noclasssummary
-noclasssummary
|
|
(Command line) |
|
<NoClassSummary enabled="true"|"false" />
|
|
(XML book file) |
|
-
Do not generate Class Summary on the package pages.
- noclasstree
-noclasstree
|
|
(Command line) |
|
<NoClassTree enabled="true"|"false" />
|
|
(XML book file) |
|
-
Do not generate the class tree (hierarchical) diagram at the top of each
class page (
enabled="true").
- nodeprecated
-nodeprecated
|
|
(Command line) |
|
<NoDeprecated enabled="true"|"false" />
|
|
(XML book file) |
|
-
Do not include
@deprecated information
(enabled="true").
- noexecutebatch
-noexecutebatch
|
|
(Command line) |
|
<NoExecuteBatch enabled="true"|"false" />
|
|
(XML book file) |
|
-
Do not execute the batch program (
enabled="true").
Use this option with -batch to generate the batch file but
not run it. This option enables you to modify the batch file or move
all files to another machine before running it. (You then run it
manually, from the command line.)
- noinheritedsummary
-noinheritedsummary
|
|
(Command line) |
|
<NoInheritedSummary enabled="true"|"false" />
|
|
(XML book file) |
|
-
Do not generate the inherited member summary information
(
enabled="true"). (The inherited member summaries
are displayed as tables after the member summaries on each
class page.)
- nooverview
-nooverview
|
|
(Command line) |
|
<NoOverview enabled="true"|"false" />
|
|
(XML book file) |
|
-
Do not generate the overview page (
enabled="true").
- nopackagepage
-nopackagepage
|
|
(Command line) |
|
|
(No equivalent for XML book file)
|
|
|
|
-
Do not generate the package pages created from the
package.html
files for each package. This includes the package name,
package description, and the class summary table for that package.
The class summary table is a list of the classes in that package
with a one-sentence description of each class.
(This option was named -noclasssummary in earlier
pre-betas.)
This option has no XML book file element equivalent.
If you are using an XML book file and do not want the
package pages generated, there are two cases:
If using <InsertAPIDoc>,
you should omit its packages argument.
If you are listing all the classes by name
in the XML book file, you should omit the
<Package> elements from that list.
- nopackageprehead
-nopackageprehead
|
|
(Command line) |
|
<NoPackagePreHead enabled="true"|"false" />
|
|
(XML book file) |
|
-
Do not generate the word "Package" in the title at the start
of each package page (
enabled="true"). When set
false (or when the command line option is omitted),
the word "Package" appears above the package name. For example,
for the java.applet package:
Package
java.applet
Setting this option true would cause the word
"Package" to be omitted:
java.applet
You also have the option to change the text in the package
title from the package name (shown above) to any text.
See Titles In Overview,
Package and Class Sections.
- nopackagesummary
-nopackagesummary
|
|
(Command line) |
|
<NoPackageSummary enabled="true"|"false" />
|
|
(XML book file) |
|
-
Omit the table of packages from the overview page (
enabled="true").
When this option is turned off (enabled="false"), the table of packages
lists all documented packages with a one-sentence description of each,
grouped by the -group
option.
- noqualifier
-noqualifier all | [overview-tree:]pkgname1:pkgname2:...
|
|
(Command line) |
|
<NoQualifier> default | all | [overview-tree:]pkgname1:pkgname2:... </NoQualifier>
|
|
(XML book file) |
|
-
Omits the qualifying package name from ahead of class
and interface names in output.
The argument to
-noqualifier is either
"all" (all package qualifiers are omitted) or a
colon-separate list of package names (wildcards allowed), to be
removed as qualifiers. The term "overview-tree"
is optional and removes all qualifiers from the inheritance tree
that appears on the overview page (when
-overviewtree
is specified). The "default" argument is identical
to omitting the option altogether, so is useful for keeping
the option in the XML book file as a placeholder for future
use. Multiple noqualifier options are cumulative.
The following example omits all package qualifiers from everywhere
including the overview tree:
-noqualifier all
Same as above:
-noqualifier overview-tree:all
The following example omits all package qualifiers from only
the overview tree:
-noqualifier overview-tree
The following example omits all package qualifiers from the
overview tree and only the java.lang package qualifier from
everywhere else:
-noqualifier overview-tree:java.lang
The following example omits "java.lang" and "java.io" package qualifiers
from everywhere but the overview tree:
-noqualifier java.lang:java.io
The following example omits package qualifiers starting with "java",
and "com.sun" subpackages (but not "javax") from everywhere but
the overview tree:
-noqualifier java.*:com.sun.*
- nosince
|
|
<NoSince enabled="true"|"false" />
|
|
(XML book file) |
|
-
Omits the "Since" sections derived from the
@since tags. It omits
these sections from the package and class pages, and from the column in the almanac pages.
This option is essentially identical to the
-nosince option
in the standard doclet.
- noxrefpagenumber
-noxrefpagenumber
|
|
(Command line) |
|
<NoXRefPageNumber enabled="true"|"false" />
|
|
(XML book file) |
|
-
By default, subscript page numbers automatically appear after each
internal cross-reference.
This option prevents the subscript page numbers (shown below)
from appearing. The subscript in this example means go to page
10 for more details.
AppletContext10
The "Subscript Page Only" cross-reference format determines
what the subscript looks like.
- overviewfile
-overviewfile htmlfile |
|
(Command line) |
|
<OverviewFile> htmlfile </OverviewFile>
|
|
(XML book file) |
|
-
Imports overview documentation from htmlfile, an HTML file.
You should write an overall description of the set of packages being documented in
this HTML file. The MIF Doclet inserts this description at the top of the
generated overview page followed by an automatically-generated table listing all
package names with the first sentence description of each package
from each package.html file.
If omitting the command line option and not using an XML book file,
the generated overview page still lists the packages but contains no user-supplied
overview description. Use
-nooverview for omitting the entire
overview page.
For more information about this option and how to format the "source"
htmlfile, see
-overview option in the Javadoc core options.
See XML Book File - Chapters for
how to use this option.
- overviewtitle
-overviewtitle text |
|
(Command line) |
|
<OverviewTitle> text </OverviewTitle>
|
|
(XML book file) |
|
-
Specifies a title for the overview page
(
overview.mif).
If the -overviewtitle option is omitted,
the text "Overview" appears as the title.
The text argument is passed through without any processing.
This option serves the same function as
-doctitle in the standard doclet.
However, in contrast, -overviewtitle should not contain
HTML tags. (This option was named -doctitle during early beta.)
Also see -replacetitlestr,
for setting the title on the title page.
- overviewtree
-overviewtree |
|
(Command line) |
|
<OverviewTree enabled="true"|"false" />
|
|
(XML book file) |
|
-
Generates a hierarchical diagram, or overview tree, showing the inheritance
relationship of all classes and interfaces at end of the overview page.
- package (Command line)
|
|
|
(No equivalent for XML book file)
|
|
|
|
-
Shows only package-private, protected, and public classes and members.
This option is identical to the
-package
option in the Javadoc core options.
- package (XML book file)
|
(No equivalent for command line)
|
|
|
|
<Package> packagename </Package>
|
|
(XML book file) |
|
-
Generates and inserts the package page for the specified
packagename. This option has no command line equivalent,
and is not to be confused with
-package.
Example:
<Package> java.lang </Package>
You also have the option to change the text in the package
title from the package name (shown above) to any text.
See Titles In Overview,
Package and Class Sections.
- print
-print pdf | printer | miffile | fmfile
|
|
(Command line) |
|
<Print> pdf | printer | miffile | fmfile </Print>
|
|
(XML book file) |
|
-
NOTE - This option requires
fmbatch or
dzbatcher.
Prints to printer, PDF or PS, according to the specified print
settings. Only one -print option is allowed per run of
the MIF doclet.
pdf - generates a PDF file, replacing the .book
extension with .pdf. Therefore, a PDF file named
api.pdf is generated from the default book file
named api.book. This option uses the default settings
file print-pdf.fm
that is written to the fm directory during each run.
You would call this as:
-print pdf
printer - prints to the default printer.
This option uses the default settings file
print-printer.fm
that is written to the fm directory during each run.
You would call this as:
-print printer
- fmfile - A print settings file in FrameMaker format. This
filename has an absolute path or a path relative to the current
directory from where the doclet is started.
You can create your own settings file or copy and modify the default
ones,
print-pdf.fm and print-printer.fm,
listed above.
For example, you could copy the fm/print-pdf.fm
file to the current directory and modify it to save each FrameMaker
file to a separate PDF file. You would call this file as:
-print print-pdf.fm
- miffile - A print settings file in MIF format. Otherwise
identical to the fmfile argument.
The option uses print settings saved in the settings file such as
range of pages to print, print in reverse page order, print even/odd
pages only, print to a printer or file (PS or PDF), how to print to PDF
(as a single PDF file or one PDF file per FrameMaker file), and
which printer to print to. (It does not print any pages or content
of the settings file.) When printing to a file, the "Destination"
path is ignored (as it is hard-coded into the MIF Doclet when writing
the mif/mif-to-fm.batch file).
Also, any "Acrobat Setup" settings are ignored. To set these,
set them in the default or custom template.
In the testing we did (in FrameMaker 5.5 on Solaris), in order to create
a PS settings file, you need to both choose destination "Postscript File"
and uncheck "Generate Acrobat Data" in the FrameMaker print dialog box.
Leaving the latter checked will cause the destination to change to "PDF File".
(It doesn't matter what filename you use for the Postscript file -- that
name is overridden by the filename of the file being converted to Postscript.)
For more information about printing to PDF, see
Creating PDF.
To save as Microsoft Word or WordPerfect, use the "Save As"
menu option in FrameMaker.
- private
|
|
|
(No equivalent for XML book file)
|
|
|
|
-
Shows all classes and members regardless of access modifier.
This option is identical to the
-private
option in the Javadoc core options.
- protected
-protected
|
|
(Command line) |
|
|
(No equivalent for XML book file)
|
|
|
|
-
Shows only protected and public classes and members. This is the default.
This option is identical to the
-protected
option in the Javadoc core options.
- public
|
|
|
(No equivalent for XML book file)
|
|
|
|
-
Shows only public classes and members.
This option is identical to the
-public
option in the Javadoc core options.
- replacetitlestr
-replacetitlestr fromstring tostring
|
|
(Command line) |
|
<ReplaceTitleStr> fromstring tostring </ReplaceTitleStr>
|
|
(XML book file) |
|
-
Searches for all instances of the fromstring in the title page
titlepage.fm and replaces each one with tostring.
- fromstring is case-sensitive and must appear in
titlepage.fm with leading and trailing white space.
For example, searching for "name" will find only the lowercase
word "name" but no other string -- not "Name", "NAME" or "filename".
To ensure uniqueness, our convention for placeholders is to enclose
the text within brackets, such as "[BookTitle]".
Using angle brackets may confuse the XML parser.
- tostring is the replacement string, which is
inserted exactly as specified (there is no case matching).
Special characters can be expressed as a MIF code, as found in the
Special MIF Characters table.
The default file titlepage.fm contains seven placeholder
strings that can be replaced; each one is enclosed in square brackets,
such as [BookTitle], to set them apart from normal text.
Here are examples of each:
-replacetitlestr "[BookTitle]" "Real-Time Java\xaa Specification"
-replacetitlestr "[BookSubTitle]" "Threads"
-replacetitlestr "[BookVersion]" "Version 1.0"
-replacetitlestr "[BookAuthor]" "James Gosling"
-replacetitlestr "[BookPublisher]" "Addison-Wesley"
-replacetitlestr "[BookCopyright]" "Copyright \xa9 2000 Sun Microsystems, Inc."
-replacetitlestr "[BookDedication]" "Dedicated to my mom"
The [BookCopyright] example above shows how to use
"\xa9" for the copyright symbol ©.
Notice that for the final text to contain a space between the
symbol © and the year, MIF requires that you include two
spaces between "\xa9" and the date, as shown.
The same is true for "\xaa" and the
TM symbol, as shown above
in [BookTitle].
- sectionfile
|
(No equivalent for command line)
|
|
|
|
<SectionFile> htmlfile </SectionFile>
|
|
(XML book file) |
|
-
Specifies a section of the book, which corresponds to one file.
The section file can be in any part of the book:
<FrontMatter>, <Chapters>,
or <BackMatter>. A chapter can be composed
of one or more section files. A section file does not import
template.mif (true). For examples of how this element is used,
see Chapter from HTML, MIF or FM File
and the section that follows it.
- setuservariable
-setuservariable name value
|
|
(Command line) |
|
<SetUserVariable> name value </SetUserVariable>
|
|
(XML book file) |
|
- Defines a FrameMaker user variable name and set it to value.
User variables can be used in body pages or master pages, such as in running
headers or footers. These variables end up appearing in the
Special >
Variables FrameMaker menu.
By default, name must be UserVariableN,
where N is an integer, such as UserVariable1 and
UserVariable2:
-setuservariable UserVariable1 "Heroes of Zanzibar"
-setuservariable UserVariable2 "Janice Kovar"
To use a different name, you must remap the name in a copy of the
stylemap.properties file.
In this example, the entries in the properties files might look
like:
UserVariable1 MyBookName # Variable defined by user
UserVariable2 MyBookAuthor # Variable defined by user
Then the options would be:
-setuservariable MyBookName "Heroes of Zanzibar"
-setuservariable MyBookAuthor "Janice Kovar"
User variables must be added to stylemap.properties
in the format UserVariableN where N
is an integer starting from 1. There is no limit to the number
of user variables, with the caveat that they must first be
defined in the template. The default template.mif
defines only the first four user variables, so if you want more,
you need to add them to the template and use the
-importformats option.
The values for the user variables must be defined in consecutive
order -- that is, you cannot define a value for
UserVariable1 then another value for
UserVariable3 without first
defining a value for UserVariable2.
To include special characters in value, see
Special MIF Characters.
- sortmembers
-sortmembers group:az | group:source | nogroup:az |
|
|
(Command line) |
|
<SortMembers> group:az | group:source | nogroup:az </SortMembers>
|
|
(XML book file) |
|
-
Sets the grouping and ordering of members in a class.
This option has no effect on the order of items in the Member
Summary table.
The argument is composed of two keys: group/nogroup for grouping,
and az/source, for order within a group:
group:az - Generates subheadings for the three groups
Fields, Constructors and Methods; lists the
members within each group alphabetically. This is the default.
group:source - Generates subheadings for the three groups
Fields, Constructors and Methods; lists the
members within each group in the order their declarations
occur in the source files.
(New in 1.2 Beta 2)
nogroup:az - Orders all fields, constructors,
and methods together into a single alphabetical list.
This style is how a common dictionary would order the members.
There is no "nogroup:source" option, as source code is
naturally grouped -- use "group:source" instead.
NOTE: For backward compatibility with 1.2 Beta 1, argument "az"
is shorthand for "nogroup:az", and "group" is
shorthand for "group:az".
- sourcepath
-sourcepath pathlist
|
|
(Command line) |
|
|
(No equivalent for XML book file)
|
|
|
|
-
Points to one or more directories pathlist that hold the
package directories to be documented. Also see
-sourcepath
option in the Javadoc core options.
- split
-split package | class
|
|
(Command line) |
|
<Split> package | class </Split>
|
|
(XML book file) |
|
-
Generates one MIF (and FrameMaker) file per package or class.
package - Generates one file per package. All
package files are put in a single directory. Each package
file contains the package documentation as well as all class
documentation for that package. The order of the classes
is alphabetic by default, but can be changed to
any order you prefer
in the XML book file. (This argument is the default
if -split is omitted the command line.)
class - Generates a separate file for each
package and class and puts them into package directories.
The files are ordered in the FrameMaker book file with
all package files first, in alphabetic order, followed by
all class files, in alphabetic order by class name (rdgardless
of package). There is no option to change the order.
Examples of both cases follow for generating documentation for the
java.applet and java.awt packages:
-split package
titlepage.fm
contents.fm
overview.fm
java.applet.fm (documents all classes in java.applet)
java.awt.fm (documents all classes in java.awt)
index.fm
-split class
- (Shown with Solaris directory separator "
/".
Windows separator would be "\")
titlepage.fm
contents.fm
overview.fm
java/applet/package-summary.fm
java/awt/package-summary.fm
java/awt/ActiveEvent.fm
java/awt/Adjustable.fm
java/awt/AlphaComposite.fm
java/applet/Applet.fm
java/applet/AppletContext.fm
java/applet/AppletStub.fm
java/applet/AudioClip.fm
java/awt/AWTEvent.fm
java/awt/AWTEventMulticaster.fm
java/awt/AWTEventPermission.fm
java/awt/BasicStroke.fm
...
index.fm
Whether passing in class or package,
when printing to PDF, you have the choice of printing
to one PDF file per book (the default) or one PDF file per
FrameMaker file. Internal links work in all cases.
For a more complete list of generated files, see
Split Package
or Split Class
in Generated Files.
- stylemapfile
-stylemapfile file.properties
|
|
(Command line) |
|
<StylemapFile> file.properties </StylemapFile>
|
|
(XML book file) |
|
-
Specifies the file that maps internal styles to FrameMaker styles.
This option is necessary only if you want to change the mapping from
the default mapping. Use argument
stylemap.properties to use
the built-in (default) file located inside the mifdoclet.jar
file:
-stylemapfile stylemap.properties
The above option looks in the current directory from where the doclet
is started before using the built-in version.
To override the default, copy this file from the
resources directory to another
name or location; in the latter case, use path ahead of the
filename, where path can either be an absolute path or
a path relative to the current directory:
-stylemapfile ./mystylemap.properties
You might use this option if your company has its own FrameMaker
style names, style definitions and template -- it lets you map the
MIF doclet's internal style names to your company's style names.
- summarytablefirstcolumn
-summarytablefirstcolumn width | default
|
|
(Command line) |
|
<SummaryTableFirstColumn> width | default </SummaryTableFirstColumn>
|
|
(XML book file) |
|
-
Sets the width of the first column in summary tables. The
values can be expressed in any of the dimensions shown in
table width dimensions
or as a percentage of the column width.
Automatically reduces the width of the second column by the
same amount to keep the overall width constant (summary tables
have only two columns).
The value default means use the default value of
130 points, which is designed for the default 8.5 x 11"
template.mif. Omitting this option is the
equivalent to using the value default.
A summary table is a table that the doclet automatically constructs
from declarations and summary sentences. This includes the Package Summary,
Class Summary, Member Summary, and Inherited Member Summary.
Examples:
-summarytablefirstcolumn 1.5in
- Set the first column width to 1.5 inches.
-summarytablefirstcolumn default
- Set the first column width to the default 130 points.
-summarytablefirstcolumn 30% -columnwidth 4.5in
- Set the first column width to 30% of 4.5 inches, or
1.35 inches.
Also see -columnwidth.
- titlefile
-titlefile miffile | fmfile
|
|
(Command line) |
|
<TitleFile> miffile | fmfile </TitleFile>
|
|
(XML book file) |
|
-
Use this option to specify the file used for the title page.
Default Title File -
To generate the default title page, pass in titlepage.mif
or titlepage.fm:
<TitleFile> titlepage.mif </TitleFile>
Results: In this case, the doclet copies the resource file
titlepage.mif from mifdoclet.jar
to the mif (or fm) destination directory and imports formats from
template-roman.mif.
Custom Title File -
To supply a title file you have modified, you must rename or
relocate it. For example:
<TitleFile> mytitlepage.mif </TitleFile>
You can precede the specified file by a path that is absolute, or is
relative to the current directory from where the MIF doclet is started.
If you want to use the default name and keep it in the current
directory, you can do so by prefixing it with the current directory:
<TitleFile> ./titlepage.mif </TitleFile>
Results: When specifying a custom title file, the doclet copies the
specified title page file to the mif (or fm) destination
directory and includes it in the generated FrameMaker book file
as a .fm file. (If the file is not found,
the MIF Doclet prints a warning and continues.)
The doclet does not import formats into that file,
even if -importformats is specified.
This enables you to modify that custom file without regard
to the styles in the imported template.
Setting up the custom title file - Apply the master page on
the first page of this custom title file as you would like it
to end up (the name of this first master page can be any name
you want). Set up the master pages named "Left" and "Right"
to have the layout you want for the subsequent title pages.
Set the page number style to arabic (1, 2, ...) or roman numeral
(i, ii, ...). If this is the first file in the book, this
style will determine how the page number style of the front matter.
Command Line Note -
If you are running the MIF doclet strictly from a command on
the command line to (and not calling an XML book file),
the title page file is generated by default even
when this option is omitted from the command line.
- verbose
|
|
<Verbose enabled="true"|"false" />
|
|
(XML book file) |
|
-
Provides more detailed messages while javadoc is running.
This option is identical to the
-verbose option
in the Javadoc core options.
- version
|
|
<Version enabled="true"|"false" />
|
|
(XML book file) |
|
-
Creates a "Version" subhead at the end of the class description,
followed by the text from the
@version tag. You can have
only one @version tag per class. Example:
Version: 1.2 Beta1
This option is the same as the
-version option
in the Javadoc core options.
Obsolete Options
The following list shows options that no longer exist along with
their replacements. For brevity, only the command line option
is shown even if the option has an XML equivalent (thus,
<CommentTableWidth> has been renamed to
<ColumnWidth>).
Options in Version C:
-bookfile has been renamed to
-bookfilename.
-overview has been replaced by
-overviewfile.
-doctitle has been replaced by
-overviewtitle
and -booktitle.
-includedir has been removed, as
-importformats
is a much easier way to import a custom template.
-tftag and -textrectid (and -trectid)
have been removed, as they are no longer necessary.
Options in pre-release versions of 1.2Beta 1:
Special MIF Characters
Some of the special characters commonly used in English
are defined in the following table. The right column
shows the MIF character you would type into an option's argument
string, such as the trademark (JavaTM)
and copyright symbols (Copyright © 2001) shown here:
-booktitle "Sample Packages" \
-booksubtitle "for Java\xaa" \
-bookcopyright "Copyright \xa9 2001 Duke, Inc." \
For a complete list of these characters, go to the online help
for FrameMaker, and under "Online Manuals" entry, look for the document
"FrameMaker Character Sets".
| Desired Character | MIF Character
| Tab | \t
| New line without new paragraph | \r
| End of paragraph | \p (lowercase p)
| Start of paragraph | \P (uppercase P)
| Normal (breaking) space | \s
| Nonbreaking space | \ (space)
| Thin space | \st or \i
| En space | \sn or \N
| Em space | \sm or \M
| Numeric space | \s# or \#
| Discretionary hyphen | \- (hyphen)
| En dash | \xd0
| Em dash | \xd1
| Bullet | \xa5
| Straight double quote | \x22
| Straight single quote | \x27
| Left curly double quote | \xd2
| Right curly double quote | \xd3
| Left curly single quote | \xd4
| Right curly single quote | \xd5
| Trademark symbol TM | \xaa
| Registered trademark symbol ® | \xa8
| Copyright symbol © | \xa9
| | | | | | | | | | | | | | | | | | | | | | | |
XML Book File
An XML book file contains XML elements that serve two purposes:
(1) to specify the files to include in the book and their
order, and (2) to substitute for command line options.
When writing a Javadoc command with options to run the MIF Doclet,
you have a choice of using only command line
options or using an XML book file instead, with as few as
five command line options in the actual command. You call
the XML book file with the
-book option.
Here is a sample XML book file:
XML book file
It contains the available options, with typical arguments
for those options. Notice, unlike command line options,
the boolean options can be turned on an off by changing
enabled to true or false -- you don't have
to remove an option to disable it.
We have no DTD or schema for the XML book file.
Front Matter, Chapters and Back Matter
Each XML book file has three parts: front matter,
chapters, and back matter:
(As XML options are introduced, they have links to
their documentation.)
<Book>
<FrontMatter>
<!-- Put front matter here -->
</FrontMatter>
<Chapters>
<!-- Put chapters here -->
</Chapters>
<BackMatter>
<!-- Put back matter here -->
</BackMatter>
</Book>
NOTE - When editing an XML book file, it is useful
to verify that the XML elements are well-formed (such as
each start element has a corresonding end element).
You can check this by opening the file in a program
that interprets XML, such as Internet Explorer.
Front Matter
Here is the generic order of front matter
recommended by the Chicago Manual of Style:
<FrontMatter>
<SectionFile> halftitlepage.html </SectionFile>
<TitleFile> titlepage.mif </TitleFile>
<SectionFile> copyright.html </SectionFile>
<SectionFile> dedication.html </SectionFile>
<ContentsFile> contents.mif </ContentsFile>
<SectionFile> foreword.html </SectionFile>
<SectionFile> preface.html </SectionFile>
</FrontMatter>
The half title page is the first right-hand page inside
the cover -- traditionally, it contains only the title,
not the author or publisher.
The only two front matter files supplied with the MIF Doclet
are titlepage.mif and contents.mif.
Notice they have special XML elements <TitleFile>
and <ContentsFile>.
They are included in the internal resources
directory of mifdoclet.jar, and those internal
files are used if you supply those exact names (or their
.fm equivalent). To use your own file, you
must supply a different filename or path.
Concatenation of files in front matter -
When there are two or more <SectionFile> lines together
within the front matter that both contain HTML files, the files are
not concatenated,
and they are written to separate MIF and FM files. Such a case is shown
in the example above with the copyright.html and
dedication.html files. (However, in a chapter,
the two files are concatenated into a single MIF file, as described later.)
An MIF or FM file can appear in <SectionFile>
option. For instance, the file preface.html above
could be replaced with preface.mif or preface.fm.
When generating the table of contents, it builds the entries
from these headings:
ChapterHead
ChapterSubHead
OverviewHead
PackageHead
ClassHead
AlmanacClassHead
IndexHead
To automatically update the table of contents entries and page
numbers, you must use the -batch option.
Chapters
The chapters part is the main body of the book where you include
the API documentation and any other documentation.
The following section describes how to arrange the packages and
classes alphabetically or logically. It then describes how to
include sections from HTML, MIF or FrameMaker files.
Including Overview File - The overview file generated
by the MIF Doclet contains a list of all documented packages
with one-sentence descriptions of each, plus a narrative
description that you can write. In this example, the
narrative description is in overview.html:
<Chapters>
<OverviewFile> overview.html </OverviewFile>
</Chapters>
Arranging Packages and Classes Alphabetically - It's easy to
create a book that contains only documentation from declarations
and doc comments, with no additional documentation --
the same content generated by the Javadoc standard doclet.
The option <InsertAPIDoc> inserts all
packages and classes specified at the command line, arranged
either split by classes or packages
(split by package is the default), and sorted alphabetically.
Include <InsertAPIDoc> in the
<Chapters> part but not in a
<Chapter> element.
<Chapters>
<InsertAPIDoc> packages classes </InsertAPIDoc>
</Chapters>
When split by package, each package starts a new chapter.
If you want all packages in the same chapter, arrange them
logically, using the next section.
Arranging Packages and Classes Logically - If you want to
arrange the packages and classes in a logical, rather than
alphabetical, order, you must use the
-split package option
(which is the default); then specify the packages explicitly,
and specify class names within a package in the order you want,
as shown here. If you want to include them, you must also explicitly
list the nested classes (both static and non-static). You cannnot mix
classes from different packages in the same chapter.
The <Chapter> element enables
its first page to start on a right-hand page, and gives you the
option of numbering the chapter. The first <Package>
element below generates documentation from the file
java/lang/package.html.
<Inter> is equivalent to <Interface>.
NOTE - To facilitate creating this list, you can run
the MIF doclet once using <InsertAPIDoc>
which generates a snapshot list of
packages and classes similar to the following one. You can
find this list in the
resources/snapshots directory -- the filename
starts with the name classlist and is time stamped.
<Chapters>
<Chapter>
<Package> java.lang </Package>
<Class> java.lang.Object </Class>
<Class> java.lang.Number </Class>
<Class> java.lang.Double </Class>
<Class> java.lang.Float </Class>
<Class> java.lang.Long </Class>
<Class> java.lang.Short </Class>
<Class> java.lang.Integer </Class>
<Class> java.lang.Byte </Class>
<Class> java.lang.Character </Class>
...
</Chapter>
<Chapter>
<Package> java.util </Package>
<Inter> java.util.Collection </Inter>
<Inter> java.util.Set </Inter>
<Inter> java.util.SortedSet </Inter>
<Inter> java.util.Map </Inter>
<Inter> java.util.SortedMap </Inter>
<Inter> java.util.List </Inter>
<Inter> java.util.Iterator </Inter>
<Inter> java.util.ListIterator </Inter>
</Chapter>
</Chapters>
NOTE - Packages that you are documenting must appear
on the command line (their order there is immaterial) in
order to be included in the generated book,
and again explicitly in the XML book file only if you want
to change their order or add chapter titles or chapter
numbering to them.
Chapter from HTML, MIF or FM File -
A chapter can also contain material that is written separately in
HTML, MIF or FM files, rather than derived from doc comments in
.java source files.
HTML source files are converted to MIF, but MIF and FM files
are totally unprocessed by the MIF doclet -- their filenames are
merely added to the FrameMaker book file and the files are copied to
the appropriate MIF or FM destination directory. Therefore, if you
want a MIF or FM file to have a chapter heading and chapter number,
you must manually add that to the file. You can do this
conveniently by copying a previously-generated chapter that was
generated from an HTML file.
Examples of such chapters might include an introduction or a
description of overall goals or design concepts. Such a chapter must
use a <SectionFile> element to specify the path and
filename. A chapter can be composed of multiple HTML, MIF or FM files.
Headings within an HTML file convert as follows:
- All
<H1> headings convert to ChapterHead
- All
<H2> headings convert to ChapterSubHead
- All
<H3> headings convert to ChapterSubSubHead
- All
<H4>, <H5> and <H6> headings convert to ChapterSubSubSubHead
Concatenation of Files -
When there are two or more <SectionFile> lines together
within a chapter that both contain HTML files, the files are concatenated into
a single MIF or FM file. The last character of the first HTML file is followed
immediately by the first character of the HTML second file. Such a case is
shown in the example below with the introduction.html followed
by the perspective.html file. (Note that given the same two
<SectionFile> lines with HTML files in a front matter
or back matter section, the second file would start on a new page.)
In contrast, MIF and FM files in <SectionFile> options
always start new pages.
In this example, the introduction and perspective sections are generated from
an HTML file, the goals chapter is a MIF file, and the design chapter is an
FM file. The overview file is a separate chapter followed by one or more
chapters of packages and classes.
<Chapters>
<Chapter>
<SectionFile> introduction.html </SectionFile>
<SectionFile> perspective.html </SectionFile>
</Chapter>
<Chapter>
<SectionFile> goals.mif </SectionFile>
</Chapter>
<Chapter>
<SectionFile> design.fm </SectionFile>
</Chapter>
<Chapter>
<OverviewFile> overview.html </OverviewFile>
</Chapter>
<InsertAPIDoc> packages classes </InsertAPIDoc>
</Chapters>
Chapter with Alternating API and HTML Text Sections - A chapter
can alternate between API documentation for a class and supplemental
HTML text, such as examples. As usual, each HTML file should
appear within a <SectionFile> option -- the
filename's path is relative to the package directory. (The MIF Doclet
looks ahead and identifies which package is being documented.)
Therefore, you can put these HTML files either directly in the
package directory alongside the .java source files,
or in a doc-files subdirectory, as shown below.
Restriction - 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
(from where the doclet is started).
You can still intersperse <SectionFile> options
between classes. If you omit the <Package> options,
you can put <SectionFile> ahead of each list of classes.
The example chapter below starts with the description
package-intro.html followed by the package description
for java.applet (from package.html),
then the Applet class and member description, followed
by a code example for Applet, then the AppletStub
class and member description, followed by a code example for that class:
<Chapters>
<Chapter>
<SectionFile> doc-files/package-intro.html </SectionFile>
<Package> java.applet </Package>
<Class> java.applet.Applet </Class>
<SectionFile> doc-files/AppletExample.html </SectionFile>
<Inter> java.applet.AppletStub </Inter>
<SectionFile> doc-files/AppletStubExample.html </SectionFile>
</Chapter>
</Chapters>
Back Matter
Here is the generic order of back matter
recommended by the Chicago Manual of Style:
<BackMatter>
<SectionFile> appendix.html </SectionFile>
<SectionFile> glossary.html </SectionFile>
<SectionFile> bibliography.html </SectionFile>
<IndexFile> index.mif </IndexFile>
<SectionFile> colophon.html </SectionFile>
</BackMatter>
The only back matter file supplied with the MIF Doclet is
index.mif. It is included in the internal
resources directory of mifdoclet.jar,
and that internal file is used if you supply its exact name
(or their .fm equivalent). To use your own file,
you must supply a different filename or path. For more
information, see -indexfile.
Concatenation of files in back matter -
When there are two or more <SectionFile> lines together
within the back matter that both contain HTML files, the files are
not concatenated, exactly as described in
front matter.
Master book and 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 typically
provides the default options, while the subbook provides
the front matter, chapters, back matter, and might override
some options. See the XML
master/subbook example and -book.
The command line needs to call the subbook:
-book subbook.xml
In this case, the subbook.xml file then calls the
master book:
<IncludeBook> masterbook.xml </IncludeBook>
Other Options - All but about 14 of the command line
options have XML book file equivalents. The options are described
at features.
There is a <ChapterNumbering> option to choose
whether or not to number the chapters.
Other options can change the appearance and content
of the class documentation, whether to include member summary tables,
whether to include class hierarchy trees, and so forth.
Inserting Comments - Comments in an XML book file are
specified the same as ordinary HTML comments: They start with
<!-- and end with -->.
They can span multiple lines, though they cannot
nest.
Snapshots
The MIF Doclet generates a snapshots into a snapshots
directory every time it is run on an XML book file. A book file
snapshot is generated with its filename time-stamped as
bookfile-yymmdd-hhmm.html.
If the XML book file contains subbooks, they are merged into
the snapshot file, which can help with troubleshooting.
For example, an XML book file generated at 14:15 (2:15pm)
on December 5, 2000 would have the filename:
bookfile-001205-1415.xml
The MIF Doclet also generates a snapshot of the list of
packages and classes for each run, similarly time-stamped as
classlist-yymmdd-hhmm.html.
It is in a format that can be pasted into an XML book file.
Javadoc Tags
The MIF Doclet is compatible with doc comments written for the standard doclet.
It uses exactly the same set
Javadoc
tags (such as @return, @param and
@see) that the standard doclet uses.
There are a few differences and constraints, described here.
@throws
This section is about how a "throws" clause is documented.
If a method declares that it throws a class, but if the doc
comment doesn't explicitly define @throws, then
the MIF doclet acts as if there is a @throws tag
and documents it accordingly: It generates a "Throws" subhead
with the class name along with a subscript page number
cross-reference to the class itself (so no text is needed
with the subhead).
@see and {@link}
The @see and {@link} tags have a
few contraints. If they link to external documents,
those links will not be live.
Running
MIF Doclet Version Number
The version number of the MIF Doclet is automatically displayed
in the output stream every time you run the MIF Doclet. It
appears at the start of the doclet portion of the output stream.
When you call javadoc, first it runs the Javadoc tool (front-end),
which then calls the doclet (back-end). The doclet version number
appears at the point at which the doclet is called.
The doclet version number is highlighted in the following example.
% javadoc -doclet com.sun.tools.doclets.mif.MIFDoclet -docletpath...
Loading source files for package java.applet...
Constructing Javadoc information...
Generating docs/mif/overview.mif...
MIF Doclet version 1.2 beta 2 release candidate (build date: August 02)
Building tree for all the packages and classes...
Generating docs/mif/package-list...
Generating docs/mif/java.applet.mif...
Generating docs/mif/api.book.mif...
A doclet works only with a certain version (or later) of the Javadoc tool.
The doclet version number (in this case, 1.2) indicates the earliest
version of the Javadoc tool it will run with. For example,
MIF Doclet version 1.2 means that the doclet will run with Javadoc
1.2.x or later (actually, 1.2.2 or later).
Setting Up to Run the MIF Doclet
For a summary of these setup requirements, see
System Requirements.
Checklist
Perform these steps before running the MIF Doclet:
- Check the Javadoc version - You must use version 1.2.2 or later
of the Javadoc tool.
To check this, run:
javadoc -J-version
The javadoc tool version number is by definition
the same as its corresponding Java 2 SDK version number
(which is what this command returns).
- Download
and unbundle the MIF Doclet bundle. This bundle contains two
Java archive files:
mifdoclet.jar and
standarddoclet.jar.
You can place these files wherever you want as long as the
-docletpath option points to them.
You can also check the MIF Doclet version.
- Install the batch program - Printing, generating PDF files or
conversion from .mif to .fm or any other format requires FrameMaker
and, optionally, a FrameMaker batch processing program
(batch processor):
fmbatch or dzbatcher.
The batch processor lets the MIF doclet
do these operations automatically.
Here are some more details about the two batch processors:
- The
fmbatch program is included with FrameMaker
for Solaris from Adobe
and is available only on Solaris. We have successfully tested the
MIF Doclet works with versions 5.5.6 and 6.x.
(We found that version 5.5.3 does not convert to PDF.)
It does support the use of spaces in the destination directory's
path or name.
- The
dzbatcher program is from
Miramo and performs
essentially the same functions as fmbatch, but on
more platforms. We have successfully tested the MIF Doclet with
dzbatcher version 3.2.0p00 or later.
The dzbatcher program uses slightly different syntax
for batch commands than fmbatch
(using more Windows-like terms: it uses
Close <filename> instead of
Quit <filename>, and Exit instead
of Quit). Available on Windows 2000, NT4.0, Solaris 2.6
and AIX. It does not support the use of spaces in the
destination directory's path or name.
After installing the batch program, do the following:
- Include the
-batch or <Batch>
option and supply the name of the batch processor as an argument.
- Either add the batch processor's location to your operating system's
search path, or include its path with the
-batch argument.
MIF Doclet Directories
The following are the directories associated with running the MIF Doclet:
- MIF Doclet Directory
This directory is named mifdoclet1.2 by default.
This directory contains mifdoclet.jar and so is pointed
to by -docletpath.
- Current Directory
This is the current directory in the shell where the MIF doclet
is started.
The following options take files whose paths are relative to this directory:
-importformats templatefile
-contentsfile contentsfile
-indexfile indexfile
-titlefile titlefile
-stylemapfile stylemapfile
-print settingsfile
-docletpath path
- Source Directory
This directory contains the source tree, typically including
overview.html, and is pointed to by
-sourcepath. For example, if you have a package
named com.mypackage, it would contain this directory
tree and its source files:
com/mypackage/*.java
If you want, you can save chapter files here as well (in HTML,
MIF or FM format).
- Destination Directory
This directory contains the generated
files and is pointed to by -d.
The generated MIF files in are in the mif
subdirectory, the generated FrameMaker files are in the
fm subdirectory, and some genereated resource
files are in the resources subdirectory.
- FrameMaker Executable Directory
This directory holds the FrameMaker and fmbatch executables.
The following option takes an executable file whose path should point to
this directory:
-batch path/fmbatch
- dzbatcher Directory (Windows only)
This directory holds the dzbatcher executable. The following
option takes an executable file whose path should point to this directory:
-batch path/dzbatcher
Running the MIF Doclet
Note - In our tests, the MIF Doclet can take from
35 seconds and require 20MB memory to document 2 simple packages,
or take an hour and require 2000MB memory to document
all 77 packages in the Java 2 Platform, Standard Edition,
v1.3. For more details, see testing.
Before running the MIF Doclet, be sure to follow the
setup procedure above.
If you run into problems, see
troubleshooting
for known bugs, limitations, common error messages,
and workarounds.
This section contains the following procedures:
Command-Line Help
To display command-line help specific to the MIF Doclet,
execute javadoc with the -doclet,
-docletpath and -help options.
For example, running javadoc on Solaris would take the
following command. See Executing on
Windows/Solaris below for instructions on how to run this
command.
|
Solaris
javadoc \
-doclet com.sun.tools.doclets.mif.MIFDoclet \
-docletpath /usr/local/mifdoclet1.2/lib/mifdoclet.jar \
-help
Windows
javadoc ^
-doclet com.sun.tools.doclets.mif.MIFDoclet ^
-docletpath C:\mifdoclet1.2\lib\mifdoclet.jar ^
-help
|
Minimal Example (MIF)
This example is about as simple as you can get. It generates documentation
for the com.package1 and com.package2 test
packages included in the download bundle.
The two options
-doclet and
-docletpath
are required just to run the MIF doclet. The option
-J-Xmx is required only if the MIF Doclet
needs more than 64M of memory, which occurs when documenting
lots of classes.
The options -sourcepath
and -d are recommended for easy
setup and use.
This example demonstrates running the MIF Doclet with these five options.
Executing on Windows/Solaris - Here are instructions for executing
the examples in Solaris and Windows:
- On Solaris: Copy and paste this example into a file
(let's call it
runmif), execute "chmod a+x runmif"
to make it executable, change the arguments to -docletpath
and -sourcepath according to your directory structure,
and then call it by executing runmif.
- On Windows: Copy and paste this example into a file
(let's call it
runmif.bat), change the arguments to
-docletpath and -sourcepath according
to your directory structure, and then call it by executing
runmif.
|
Solaris
javadoc \
-doclet com.sun.tools.doclets.mif.MIFDoclet \
-docletpath /usr/local/mifdoclet1.2/lib/mifdoclet.jar \
-J-Xmx20M \
-d docs \
-sourcepath /usr/local/mifdoclet1.2/test/sample-src \
com.package1 com.package2
Windows
javadoc ^
-doclet com.sun.tools.doclets.mif.MIFDoclet ^
-docletpath C:\mifdoclet1.2\lib\mifdoclet.jar ^
-J-Xmx20M ^
-d docs ^
-sourcepath C:\mifdoclet1.2\test\sample-src ^
com.package1 com.package2
Options:
-doclet must be set to
com.sun.tools.doclets.mif.MIFDoclet.
-docletpath specifies
the path to and include for the MIF doclet jar file
mifdoclet.jar.
-J-Xmx20M sets the maximum
memory allocation to 20MB. (65MB is the default value
if this option were omitted). This option is included here
as a placeholder for larger values, since any large
software project will require more memory.
-d sets the destination directory
to .\docs subdirectory. Two subdirectories
are created named .\docs\mif and
.\docs\fm to hold the MIF and FrameMaker files.
-sourcepath points to
the root directory that holds the package directories to
be documented. Normally, this would a directory outside
the MIF doclet, this example is for the source files included
in the MIF doclet download bundle. The com.package1
source files are located at
/usr/local/mifdoclet1.2/test/sample-src/com/package1/*.java (Solaris)
or C:\mifdoclet1.2\test\sample-src\com\package1\*.java (Windows)
com.package1 and com.package2 are
the names of the packages being documented.
|
Result: This example creates the following directories and MIF
files (plus some resource and batch script files), but no FM or PDF files:
docs/ Root directory of generated files
mif/ MIF directory
api.book.mif FrameMaker book file
titlepage.mif Title page
contents.mif Table of contents
overview.mif Overview page listing documented packages
com.package1.mif Section describing this package and its classes
com.package2.mif Section describing this package and its classes
almanaclegend.mif Legend for almanac
almanac.mif Concise list of packages, classes and members
index.mif Index (alphabetic)
The FrameMaker book file api.book.mif file is not really
usable in this example -- you can open it, but cannot print from it
or double-click on filenames in the book to open them. This is
because a FrameMaker book file can contain only FrameMaker files,
not MIF files, and no FrameMaker files were generated in this example.
You can convert the MIF files to FrameMaker files either manually in
FrameMaker or in a batch process (using the -batch option),
as in the next example.
For a complete list of auto-generated files, see
Generated Files.
Inspecting Generated Output
For troubleshooting notes and solutions to error messages,
see Troubleshooting.
After generating the documents, you should open them
in FrameMaker and scan through them visually, looking particularly
for HTML tags in the doc comments that might not have been properly
converted to MIF. The MIF Doclet has a somewhat primitive
HTML parser for this job. See
Using HTML Tags.
If you open MIF files from the mif directory,
you will notice that all chapters are numbered "Chapter 1"
and start with page 1, and the contents and index are empty.
It's not until they are converted to FrameMaker (.fm)
files that they can be and are updated.
Note that the MIF version of the FrameMaker book file, which by
default is api.book.mif, contains links to the
FrameMaker (.fm) files, not the MIF (.mif)
files.
Minimal Batch Example (FM, PDF)
This is about the smallest possible example that runs the batch processor
fmbatch (Solaris) or dzbatcher (Windows)
and prints to PDF. It uses the -batch option to
automatically convert the MIF files to FrameMaker (.fm),
update the page numbers and cross-references, and generate the
table of contents and index. The -print option
prints the entire book to PDF.
Solaris
javadoc \
-doclet com.sun.tools.doclets.mif.MIFDoclet \
-docletpath /usr/local/mifdoclet1.2/lib/mifdoclet.jar \
-J-Xmx20M \
-batch fmbatch \
-print pdf \
-d docs \
-sourcepath /usr/local/mifdoclet1.2/test/sample-src \
com.package1 com.package2
Windows
javadoc ^
-doclet com.sun.tools.doclets.mif.MIFDoclet ^
-docletpath C:\mifdoclet1.2\lib\mifdoclet.jar ^
-J-Xmx20M ^
-batch dzbatcher ^
-print pdf ^
-d docs ^
-sourcepath C:\mifdoclet1.2\test\sample-src ^
com.package1 com.package2
Options:
-batch converts the MIF files
to FrameMaker files, updates the page numbers and cross-references.
If the table of contents and index are included (as shown
in the next example), it also updates them.
-print prints to a printer or
PDF file. This examples uses the default pdf settings.
If you want other settings, you can copy and modify the settings file
(fm/print-pdf.fm) according to
Creating PDF.
- The other options are described
in the previous example.
|
Result: In addition to generating MIF files, this command also
generates the corresponding FrameMaker (.fm) files in
the fm subdirectory.
For a complete list of auto-generated files, see
Generated Files.
docs/ Root directory of generated files
mif/ MIF directory
api.book.mif FrameMaker book file
titlepage.mif Title page
contents.mif Table of contents
overview.mif Overview page listing documented packages
com.package1.mif Section on com.package1 package and its classes
com.package2.mif Section on com.package2 package and its classes
almanaclegend.mif Legend for almanac
almanac.mif Concise list of packages, classes and members
index.mif Index (alphabetic)
fm/ FrameMaker directory
api.book FrameMaker book file
titlepage.fm Title page
contents.fm Table of contents
overview.fm Overview page listing documented packages
com.package1.fm Section on com.package1 package and its classes
com.package2.fm Section on com.package2 package and its classes
almanaclegend.fm Legend for almanac
almanac.fm Concise list of packages, classes and members
index.fm Index (alphabetic)
pdf/ PDF directory
api.pdf Entire book in PDF format
Typical Batch Example (FM, PDF)
The MIF Doclet contains many useful options for adding a title page,
table of contents and index, and customizing how compact the
information is displayed. This example demonstrates running
the MIF Doclet with these and several other typical options.
This example enables you to specify things like the book title
and author from the command line. It does not require you to ever
manually open and edit any FrameMaker (or MIF) files.
Solaris
javadoc \
-doclet com.sun.tools.doclets.mif.MIFDoclet \
-docletpath /usr/local/mifdoclet1.2/lib/mifdoclet.jar \
-J-Xmx20M \
-batch fmbatch \
-print pdf \
-d docs \
-overviewfile /usr/local/mifdoclet1.2/test/sample-src/overview.html \
-overviewtitle "Sample Packages" \
-group "Summary of Sample Packages" "com.*" \
-membersummary compact \
-booktitle "Sample Packages" \
-booksubtitle "for Java\xaa" \
-bookversion "Version 1.0" \
-bookauthor "Duke" \
-bookpublisher "Sun Press" \
-bookcopyright "Copyright \xa9 2001 Duke, Inc." \
-sourcepath /usr/local/mifdoclet1.2/test/sample-src \
com.package1 com.package2
Windows
javadoc ^
-doclet com.sun.tools.doclets.mif.MIFDoclet ^
-docletpath C:\mifdoclet1.2\lib\mifdoclet.jar ^
-J-Xmx20M ^
-batch fmbatch ^
-print pdf ^
-d docs ^
-overviewfile C:\mifdoclet1.2\test\sample-src\overview.html ^
-overviewtitle "Sample Packages" ^
-group "Summary of Sample Packages" "com.*" ^
-membersummary compact ^
-booktitle "Sample Packages" ^
-booksubtitle "for Java\xaa" ^
-bookversion "Version 1.0" ^
-bookauthor "Duke" ^
-bookpublisher "Sun Press" ^
-bookcopyright "Copyright \xa9 2001 Duke, Inc." ^
-sourcepath C:\mifdoclet1.2\test\sample-src ^
com.package1 com.package2
You can find the above scripts and the generated results in the
test/example-commmandline directory. Here is the
PDF book:
- Example
book (PDF) - Typical batch example using command line
options.
Options:
|
Result: This command generates the same list of files as shown in the
previous example.
XML Book File Example With Narrative Chapters
This example generates a book with API documentation and
narrative chapters, using an XML book file, from
the standard template. Due to its length, only the
Solaris version is shown.
Solaris - Command Line
javadoc \
-doclet com.sun.tools.doclets.mif.MIFDoclet \
-docletpath /usr/local/mifdoclet1.2/lib/mifdoclet.jar \
-J-Xmx20M \
-book book.xml \
-group "Summary of Sample Packages" "com.*" \
-sourcepath ./test/sample-src \
com.package1 com.package2
Solaris - Book File (book.xml)
<Book>
<!-- General book file -->
<!-- A subbook should include the master book at this point
<IncludeBook> masterbook.xml </Book>
-->
<Options>
<!-- BOOK OPTIONS -->
<BookFilename> api.book </BookFilename>
<Batch> fmbatch </Batch>
<BatchFilePaths> absolute </BatchFilePaths>
<NoExecuteBatch enabled="false"/>
<Destination> docs-xml </Destination>
<ImportFormats> template.mif </ImportFormats>
<Print> pdf </Print>
<StylemapFile> stylemap.properties </StylemapFile>
<Verbose enabled="false"/>
<!-- FRONT MATTER OPTIONS -->
<BookTitle> "Sample Packages" </BookTitle>
<BookSubTitle> "Generated by Javadoc\xaa" </BookSubTitle>
<BookAuthor> "Duke Nebbish" </BookAuthor>
<BookVersion> "Volume 1" </BookVersion>
<BookCopyright> "Copyright \xa9 2001 Duke, Inc." </BookCopyright>
<BookPublisher> "Sun Press" </BookPublisher>
<!-- CHAPTER OPTIONS -->
<Author enabled="false"/>
<ChapterNumbering enabled="true"/>
<ChapterString> \rCHAPTER </ChapterString>
<ColumnWidth> 470pt </ColumnWidth>
<CombineOverloads enabled="false"/>
<DeclarationHead> class </DeclarationHead>
<DescriptionHead> overview package class </DescriptionHead>
<ExcludeClasses> </ExcludeClasses>
<ImageResolution> 1440dpi </ImageResolution>
<MemberHead> args </MemberHead>
<MemberSummary> compact </MemberSummary>
<NoClassPreHead enabled="false"/>
<NoClassSummary enabled="false"/>
<NoClassTree enabled="false"/>
<NoDeprecated enabled="false"/>
<NoInheritedSummary enabled="false"/>
<NoOverview enabled="false"/>
<NoPackageSummary enabled="false"/>
<NoQualifier> default </NoQualifier>
<NoSince enabled="false"/>
<NoXRefPageNumber enabled="false"/>
<OverviewTitle> Overview </OverviewTitle>
<OverviewTree enabled="true"/>
<SetUserVariable> name value </SetUserVariable>
<SortMembers> group:az </SortMembers>
<Split> package </Split>
<SummaryTableFirstColumn> default </SummaryTableFirstColumn>
<Version enabled="false"/>
<!-- BACK MATTER OPTIONS -->
<IndexStyle> hier </IndexStyle>
<IndexOneColumn enabled="false"/>
</Options>
<FrontMatter>
<TitleFile> titlepage.mif </TitleFile>
<ContentsFile> contents.mif </ContentsFile>
<SectionFile> ./test/sample-src/doc-files/preface.html </SectionFile>
</FrontMatter>
<Chapters>
<Chapter>
<SectionFile> ./test/sample-src/doc-files/introduction.html </SectionFile>
</Chapter>
<Chapter>
<SectionFile> ./test/sample-src/doc-files/goals.mif </SectionFile>
</Chapter>
<Chapter>
<SectionFile> ./test/sample-src/doc-files/design.fm </SectionFile>
</Chapter>
<Chapter>
<OverviewFile> ./test/sample-src/overview.html </OverviewFile>
</Chapter>
<InsertAPIDoc> packages classes </InsertAPIDoc>
<!--
<Chapter>
<SectionFile> ./doc-files/package-intro.html </SectionFile>
<Package> com.package1 </Package>
<Class> com.package1.Class1 </Class>
<Class> com.package1.SubClass1 </Class>
<Class> com.package1.Interface1 </Class>
<Class> com.package1.SubInterface1 </Class>
<Class> com.package1.Interface1.NestedInterface1 </Class>
<Class> com.package1.Interface2 </Class>
<Class> com.package1.Class1.NestedClass1 </Class>
<Class> com.package1.Class1.NestedStaticClass1 </Class>
<Class> com.package1.Class1.NestedProtectedClass1 </Class>
<Class> com.package1.Class1.NestedStaticProtectedClass1 </Class>
<Class> com.package1.SubClassOfNestedClass </Class>
<Class> com.package1.ClassMIFStyles </Class>
<Class> com.package1.DeprecatedClass </Class>
<Class> com.package1.SerializableClass </Class>
</Chapter>
<Chapter>
<Package> com.package2 </Package>
<Class> com.package2.ClassInPackage2 </Class>
<Class> com.package2.CrossPackageSubClass </Class>
<Class> com.package2.Clutter </Class>
</Chapter>
-->
<Chapter>
<AlmanacFile> almanac.mif </AlmanacFile>
</Chapter>
<Chapter>
<ConstantsFile enabled="true"/>
</Chapter>
<Chapter>
<SectionFile> ./test/sample-src/doc-files/conclusion.html </SectionFile>
</Chapter>
</Chapters>
<BackMatter>
<SectionFile> ./test/sample-src/doc-files/appendix.html </SectionFile>
<IndexFile> index.mif </IndexFile>
<SectionFile> ./test/sample-src/doc-files/colophon.html </SectionFile>
</BackMatter>
</Book>
You can find the above scripts and the generated results in the
test/example-bookfile directory. Here is the
PDF book:
Options:
- XML Book File - The overall XML book
file is explained in some detail at this link.
-group - The group option
is included here as a command line option rather than an
XML book file option because the latter does not support
the wildcard '*'.
- Options - Lookup the
options at this list.
<FrontMatter> -
Defines the sections in the front part of the book.
<Chapters> - Defines
the scope of all chapters in the book, numbered or unnumbered.
<Chapter> - Defines
the scope of a chapter.
<SectionFile> -
Defines the file to be included.
<InsertAPIDoc> - This
single option causes all packages and classes to be inserted
alphabetically. This is described under
Arranging Alphabetically.
If you want to arrange the packages and classes in your own
order, you would instead use the options described next.
<Package> and
<Class> options
are commented out above. They enable you to arrange classes
These are described in detail
Arranging Logically.
<ConstantsFile/> -
Inserts the static field constants section
<BackMatter> -
Defines the sections in the back part of the book.
|
XML Master/SubBook Example
NOTE - Master/subbooks are broken in this version.
This example is identical to the previous one, but illustrates
how subbooks can call master books. The options are factored into
the master book file. This is useful if you want to define default
options that can be overridden in a subbook, or if you want
several books generated with exactly the same options.
Notice the command line calls the subbook, which then contains
an <IncludeBook> option to call the master book.
When interpreted, the <IncludeBook> option causes the master book
to expand into the subbook at that point in the XML book file.
The MIF Doclet generates snapshots
of the expanded XML book file, which is helpful both for history
tracking and for troubleshooting.
Due to its length, only the Solaris version is shown here.
Solaris - Command Line
javadoc \
-doclet com.sun.tools.doclets.mif.MIFDoclet \
-docletpath /usr/local/mifdoclet1.2/lib/mifdoclet.jar \
-J-Xmx20M \
-book subbook.xml \
-group "Summary of Sample Packages" "com.*" \
-sourcepath ./test/sample-src \
com.package1 com.package2
Solaris - Master Book File (masterbook.xml)
<Book>
<!-- Master book file -->
<Options>
<!-- BOOK OPTIONS -->
<BookFilename> api.book </BookFilename>
<Batch> fmbatch </Batch>
<BatchFilePaths> absolute </BatchFilePaths>
<NoExecuteBatch enabled="false"/>
<Destination> docs-xml </Destination>
<ImportFormats> template.mif </ImportFormats>
<Print> pdf </Print>
<StylemapFile> stylemap.properties </StylemapFile>
<Verbose enabled="false"/>
<!-- FRONT MATTER OPTIONS -->
<BookTitle> "Sample Packages" </BookTitle>
<BookSubTitle> "Generated by Javadoc\xaa" </BookSubTitle>
<BookAuthor> "Duke" </BookAuthor>
<BookVersion> "Volume 1" </BookVersion>
<BookCopyright> "Copyright \xa9 2001 Duke, Inc." </BookCopyright>
<BookPublisher> "Sun Press" </BookPublisher>
<!-- CHAPTER OPTIONS -->
<Author enabled="false"/>
<ChapterNumbering enabled="true"/>
<ChapterString> \rCHAPTER </ChapterString>
<ColumnWidth> 470pt </ColumnWidth>
<CombineOverloads enabled="false"/>
<DeclarationHead> class </DeclarationHead>
<DescriptionHead> overview package class </DescriptionHead>
<ExcludeClasses> </ExcludeClasses>
<ImageResolution> 1440dpi </ImageResolution>
<MemberHead> args </MemberHead>
<MemberSummary> compact </MemberSummary>
<NoClassPreHead enabled="false"/>
<NoClassSummary enabled="false"/>
<NoClassTree enabled="false"/>
<NoDeprecated enabled="false"/>
<NoInheritedSummary enabled="false"/>
<NoOverview enabled="false"/>
<NoPackageSummary enabled="false"/>
<NoQualifier> default </NoQualifier>
<NoSince enabled="false"/>
<NoXRefPageNumber enabled="false"/>
<OverviewTitle> Overview </OverviewTitle>
<OverviewTree enabled="true"/>
<SetUserVariable> name value </SetUserVariable>
<SortMembers> group:az </SortMembers>
<Split> package </Split>
<SummaryTableFirstColumn> default </SummaryTableFirstColumn>
<Version enabled="false"/>
<!-- BACK MATTER OPTIONS -->
<IndexStyle> hier </IndexStyle>
<IndexOneColumn enabled="false"/>
</Options>
</Book>
Solaris - Sub Book File (subbook.xml)
<Book>
<!-- Subbook file -->
<IncludeBook> masterbook.xml </IncludeBook>
<FrontMatter>
<TitleFile> titlepage.mif </TitleFile>
<ContentsFile> contents.mif </ContentsFile>
<SectionFile> ./test/sample-src/doc-files/preface.html </SectionFile>
</FrontMatter>
<Chapters>
<Chapter>
<SectionFile> ./test/sample-src/doc-files/introduction.html </SectionFile>
</Chapter>
<Chapter>
<SectionFile> ./test/sample-src/doc-files/goals.mif </SectionFile>
</Chapter>
<Chapter>
<SectionFile> ./test/sample-src/doc-files/design.fm </SectionFile>
</Chapter>
<Chapter>
<OverviewFile> ./test/sample-src/overview.html </OverviewFile>
</Chapter>
<InsertAPIDoc> packages classes </InsertAPIDoc>
<Chapter>
<AlmanacFile> almanac.mif </AlmanacFile>
</Chapter>
<Chapter>
<ConstantsFile enabled="true"/>
</Chapter>
<Chapter>
<SectionFile> ./test/sample-src/doc-files/conclusion.html </SectionFile>
</Chapter>
</Chapters>
<BackMatter>
<SectionFile> ./test/sample-src/doc-files/appendix.html </SectionFile>
<IndexFile> index.mif </IndexFile>
<SectionFile> ./test/sample-src/doc-files/colophon.html </SectionFile>
</BackMatter>
</Book>
You can find the above scripts and the generated results in the
test/example-masterbook directory. Here is the
PDF book:
Options:
<IncludeBook> - Defines the
master book to be included at this point.
|
Generated Files
Which files are generated depends on whether the split
option is set to package (the default) or class.
Split package - The following list shows how files
are generated with the "-split package" option
when generating documentation for the java.applet
and java.lang packages. The destination
directory (-d) is named docs.
The default names are shown for all filenames.
With this option, the documentation for each package is
generated to a separate MIF file in the mif
directory. As shown below, the java.applet.mif
file covers the entire java.applet package,
containing all its classes, interfaces and members.
NOTE - Directories are shown in bold.
docs/ Root directory of generated files specified by -d
mif/ MIF directory (for .mif files)
api.book.mif FrameMaker book file
titlepage.mif Title page, copyright, dedication, preface
contents.mif Table of contents (1)
overview.mif List of packages with 1st sentence summaries
java.applet.mif Description of java.applet package and its classes
java.lang.mif Description of java.lang package and its classes
almanaclegend.mif Legend describing symbols in almanac
almanaclegend.eps Illustration of almanac page showing symbols
almanac.mif Compact list of packages, classes, members (1)
constant-values.mif List of static field constant values
index.mif Alphabetic index of packages, classes, members (1)
template.mif Template that defines all FrameMaker styles
template-roman.mif Defines roman numbering style for front matter
template-indextwocol.mif Template that specifies a two-column index (2)
mif-to-fm.batch Batch file for running batch processor
package-list List of package names for resolving external refs
doc-files/ Directory for image and example files (3)
fm/ FrameMaker directory (for .fm files)
api.book FrameMaker book file
titlepage.fm Title page, copyright, dedication, preface
contents.fm Table of contents (1)
overview.fm List of packages with 1st sentence summaries
java.applet.fm Descriptions of java.applet package and its classes
java.lang.fm Descriptions of java.lang package and its classes
almanaclegend.fm Legend describing symbols in almanac
almanac.fm Compact list of packages, classes, members (1)
constant-values.fm List of static field constant values
index.fm Alphabetic index of packages, classes, members (1)
print-pdf.fm Print settings file for printing to PDF
print-printer.fm Print settings file for printing to a printer
package-list List of documented packages
pdf/ Directory containing PDf file
api.pdf Entire book in PDF format
resources/ Directory containing properties files & snapshots
stylemap.properties Mapping of internal style names to FrameMaker styles
snapshots/ Directory with history of XML book files & class lists
bookfile-001205-1415.xml Snapshot of XML book file
classlist-001205-1422.xml Snapshot of package/class list
NOTE 1 - Auto-generated file.
NOTE 2 - template-indextwocol.mif is not generated
when the -indexonecolumn option is used.
NOTE 3 - doc-files directory holds any images,
examples, source code or other files that you want copied to the
destination directory. Don't include any Javadoc tags, because
they would be ignored.
There can be one doc-files directory per package.
This directory is copied from the source tree,
if present, to the corresponding package subdirectory under the
destination directory. The generated MIF document imports any
images in this directory by reference. The doc-files
directory will not be copied unless it is in a directory that
also contains .java files.
Split class - With the "-split class"
option, the files shown above are generated except
the documentation for each class is generated to a separate
MIF (or FM) file in its package directory, along with a separate
package summary, as shown here for the java.applet
package:
docs/
mif/
java/
applet/
Applet.mif
AppletContext.mif
AppletStub.mif
AudioClip.mif
package-summary.mif
Customizing
Using HTML Tags
The MIF doclet converts HTML tags to MIF.
You can place HTML tags in four different types of files:
- source files (
.java files)
- package files (
package.html)
- overview files (
overview.html or another name)
- HTML section files (
.html files).
This section describes how those HTML tags map to
MIF, and how headings and hypertext reference
anchors are handled.
Mapping of HTML Tags
The following list describes which tags are
handled by the MIF Doclet. The second column lists what each tag converts
to in MIF. Strings enclosed in quotes in the second column
are names of actual character or paragraph tags in the default
template.mif.
When the MIF Doclet encounters an HTML tag it cannot handle, it omits
the HTML tag, dumps any text to the output, and prints to the console
a warning message "Unknown HTML" along with the tag name and name of
the member where the tag is located. The warning is useful for
identifying where you might need to manually correct the formatting.
- MIF Doclet does not handle:
<CENTER> Center tag (See NOTE 1)
- MIF Doclet handles:
Structure Tags
<!DOCTYPE> (Discarded)
<HTML> (Discarded)
<META> (Discarded)
<TITLE> (Discarded)
<HEAD> (Discarded)
<BODY> (Discarded)
<STYLE> (Discarded)
<DIV ALIGN=CENTER> Creates a new paragraph
Heading Tags in an HTML Section File
<H1> "ChapterHead"
<H2> "ChapterSubHead"
<H3> "ChapterSubSubHead"
<H4> "ChapterSubSubSubHead"
<H5> "ChapterSubSubSubHead"
<H6> "ChapterSubSubSubHead"
Heading Tags in an Overview File
<H1> "OverviewHead" (See NOTE 2. Don't use <H1> here)
<H2> "ClassSubHead" (See NOTE 3)
<H3> "ClassSubSubHead"
<H4> "ClassSubSubSubHead"
<H5> "ClassSubSubSubHead"
<H6> "ClassSubSubSubHead"
Heading Tags in a package.html File
<H1> "PackageHead" (See NOTE 2. Okay to use <H1> here)
<H2> "ClassSubHead" (See NOTE 4)
<H3> "ClassSubSubHead"
<H4> "ClassSubSubSubHead"
<H5> "ClassSubSubSubHead"
<H6> "ClassSubSubSubHead"
Heading Tags in a Class Doc Comment
<H1> "ClassHead" (See NOTE 2. Don't use <H1> here)
<H2> "ClassSubHead"
<H3> "ClassSubSubHead"
<H4> "ClassSubSubSubHead"
<H5> "ClassSubSubSubHead"
<H6> "ClassSubSubSubHead"
Heading Tags in a Member Doc Comment
<H1> "MemberHead" (See NOTE 2. Don't use <H1> here)
<H2> "MemberSubHead"
<H3> "MemberSubHead"
<H4> "MemberSubHead"
<H5> "MemberSubHead"
<H6> "MemberSubHead"
Table Tags
<TABLE WIDTH=n> Table
<TR> Table row
<TH> Table heading cell (bold)
<TD ALIGN=CENTER COLSPAN=n ROWSPAN=n BGCOLOR=c>
Table cell
Paragraph Tags in Class Description (See NOTE 5)
<P> "ClassText-1" or "ClassText-2"
<PRE> "ClassCodeFragment"
<BLOCKQUOTE> "ClassBlockquote"
<UL> <LI> "ClassBullet" (not nested)
<OL> <LI> "ClassNumbered-1" or "ClassNumbered-2" (not nested)
Paragraph Tags in Member Description (See NOTE 5)
<P> "MemberText"
<PRE> "MemberCodeFragment"
<BLOCKQUOTE> "MemberBlockquote"
<UL> <LI> "MemberBullet" (not nested)
<OL> <LI> "MemberNumbered-1" or "MemberNumbered-2" (not nested)
Paragraph Tags in Tables (See NOTE 6)
<P> "TableText"
Newline Tags
<BR> Force a new line without forcing a new paragraph
Hyperlink References (See NOTE 7)
<A HREF="ref">label</A> label (ref)
Character Tags
<FONT SIZE=s FACE=f> Font tag
<TT> "Code"
<CITE> "Italic"
<EM> "Italic"
<I> "Italic"
<B> "Bold"
<STRONG> "Bold"
<CODE> "Code"
<SUP> "Superscript"
<SUB> "Subscript"
<B><CODE> "BoldCode"
<CODE><B> "BoldCode"
<B><I> "BoldItalic"
<I><B> "BoldItalic"
<B><SUP> "BoldSuperscript"
<SUP><B> "BoldSuperscript"
<B><SUB> "BoldSubscript"
<SUB><B> "BoldSubscript"
<STRIKE> "Strikethrough"
<U> "Underline"
Entities
< less than (<)
> greater than (>)
& ampersand (&)
non-breaking space
® registered trademark
© copyright
— emdash
" double-quote (")
NOTE 1 - If you want something centered, modify
the template or create your own styles.
NOTE 2 - See Titles In
Overview, Package and Class Sections.
NOTE 3 - <H2> in an overview file maps internally to
"PackageSubHead" (because there are no overview subheads) but then maps
to "ClassSubHead" in stylemap.properties for convenience.
Similar mappings occur for <H3> through <H6>.
NOTE 4 - <H2> in a package file maps internally to
"PackageSubHead" but then maps to "ClassSubHead" in stylemap.properties
for convenience. Similar mappings occur for <H3>
through <H6>.
NOTE 5 - Notice that FrameMaker styles are prefixed with "Class" or "Member"
in the default template.mif. The main difference is that
"Member" styles are indented while "Class" styles are not.
An HTML tag maps to a "Class" FrameMaker style when it is in the class, interface,
package or overview description, and to a "Member" style when it is in the
member description.
For example, when <BLOCKQUOTE> is in a class description,
it maps to ClassBlockquote; when in a member description, it maps to MemberBlockquote.
NOTE 6 - The "Table" prefix in a FrameMaker style applies to styles inside tables,
whether in a class or member description.
NOTE 7 - Anchor tags are described in
HTML Hypertext Reference
Anchor Tags.
Titles in Overview, Package and Class Sections
The overview, package and class pages have natural titles,
which are the word "Overview", the package name and
class name, respectively. If you would like to override
the first two names, you can. (There is no override
for class section titles.) The following describes each
section separately.
Overview Section Title
The overview page has "Overview" as its default title.
You can change this with the
-overviewtitle
option.
For this reason, <H1> tags are not
recommended in overview comments, because an
<H1> tag would produce a second ChapterHead
title. (We may remove the -overviewtitle option
in a future version and use the <H1>
tag instead, because this would make it consistent with
package and HTML section titles.)
Package Section Title
By default, the package section gets its title from the name of
the package with the word "Package" above it. For example,
for the java.applet package:
Package
java.applet
Setting
-nopackageprehead
true would cause the word "Package" to be omitted:
java.applet
However, <H1> can be used in package files
(package.html) to replace the package name
in the title. For example:
<H1>The Applet Package</H1>
combined with -nopackageprehead would cause
the title to be:
The Applet Package
Class Section Title
By default, the class section gets its title from the name of
the class, with the package name just above it. For example,
for Applet class in the
java.applet package:
java.applet
Applet
Setting the -noclassprehead option true
would cause the package name "java.applet" to be omitted:
Applet
There is currently no way to change the title of the
class section. (If you have such a need, please send
us a request.)
Member Section Title
By default, the member section gets its title from the
name of the member with arguments. See the
-memberhead
tag for details on how to modify this, displaying
the full declaration (to save space) or no arguments
(when combining overloads).
HTML Hypertext Reference Anchor Tags
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 "ref" appears as text within parentheses
following the label. For example:
<A HREF="http://java.sun.com">Java Software</A>
would appear as
Java Software (http://java.sun.com)
Absolute links appear as shown above with no extra effort on your part.
Relative links appear without the parenthetical reference unless you
use hrefdocroot to establish
an absolute root. (An absolute link begins with http://
or an absolute file path like a slash '/' or
C:\.)
Creating PDF
To create a PDF version of your document, specify the
-print pdf option as described.
This is equivalent to choosing the PDF option from the Print dialog
box in FrameMaker.
One or Multiple PDF Files
You have the choice of printing each generated MIF file to a separate
PDF file or printing them all to one larger PDF file. To do this,
change the option in a copy of print-pdf.fm, as follows.
First copy and rename
print-pdf.fm.
Launch FrameMaker and choose File > Print.
In the "Destination" popup menu, choose one of these:
- PDF file for each document (one file per package)
- Single PDF file (one file for all packages)
The latter is named api.pdf by default.
Acrobat Bookmarks
The MIF Doclet automatically sets up the left-hand TOC (bookmark) list
for Acrobat with indentation as follows:
BookTitle
TOCHead
OverviewHead
PackageHead
ClassHead
IndexHead
The list actually appears in alphabetic order in the Acrobat Setup
dialog box in FrameMaker.
For example, the above setup could produce a PDF TOC list such as this:
Java 2 Platform API Specification
Contents
Packages
java.applet
Applet
AppletContext
AppletStub
AudioClip
java.awt
ActiveEvent
Adjustable
...
Index
You can modify this list (change indent levels, add or remove items)
as you see fit, according to the
Acrobat Setup procedure.
Default FrameMaker Template (template.mif)
A FrameMaker template is any FrameMaker or MIF file that contains a standard
set of styles, page layouts, formats, definitions and setups for a book.
It consists of:
- Paragraph styles
- Character styles
- Master pages (page layouts)
- Reference pages
- Table formats
- Variable definitions
- Cross-reference formats
- Acrobat setup
MIF Doclet Uses a Single Template - The MIF Doclet has an
internal, default master template file called template.mif.
This file is the master template from which all generated
MIF files (and hence FrameMaker files) are generated. To emphasize this:
The single file template.mif is used for all
files generated by the MIF doclet. This includes the API
documentation, almanac, table of contents, index and
and any other chapters or sections.
This means that this one file contains the master pages,
paragraph styles, character styles, reference pages,
cross-reference definitions, variable definitions,
and everything else for all sections of the book.
While this makes the list of styles long, this makes it quite
easy to change a style everywhere in the book -- simply
change the template and use the -importformats
option (or import it into the FrameMaker book file manually).
When you run the MIF Doclet, template.mif is copied to the
destination mif directory, where the doclet then
imports all of its formats into the generated MIF files.
A following section describes how you can customize a copy of
template.mif, such as adding or modifying a style or
master page, to modify any part of the book.
Derived Templates -
Keeping to the above principle, the MIF Doclet automatically derives
the template for front matter
and template for two-column
index from template.mif.
Viewing Style Samples -
The default template template.mif contains over 74 paragraph
styles and 15 character styles, as well as table styles and master pages.
The template itself contains examples of uses all of the styles, which you
can look at by opening the file in FrameMaker from the mif directory.
Opening this file is perhaps the best way to understand what these styles are
used for. If you are interested in how a particular paragraph style
is used, you can search for it in FrameMaker:
Choose Edit > Find/Change, choose "Paragraph tag" from
the Find popup menu, then type the name, such as "MemberHeadDeclaration", in the
Find field. Clicking the "Find" button will find text assigned with that
paragraph style.
The styles in the default template fall into two categories -- those that
the MIF Doclet applies to text, and those that are manually applied to
the template:
- Styles the MIF Doclet applies
These are all listed in the
stylemap.properties file.
This file lists all of these styles along with a comment describing how
each is used. A subset of these styles derive directly from HTML
tags in doc comments -- to see a list of these, look at the
Mapping of HTML Tags list.
This list shows how HTML tags map to FrameMaker styles.
- Styles the MIF Doclet does not apply
These include styles that are defined in the template that
are used in the part of the layout that is not modified by
the MIF Doclet. This includes running headers and footers,
which begin with "Run", such as RunFooter-L,
RunFooter-R, and so on.
Code fonts - In template.mif, the
monospaced fonts for code are defined as Courier, because that is a
commonly available font. We are Sun actually instead use Lucida Sans
Typewriter font. For code text that must be narrow, such as in the
almanac, we use Lucida Sans Typewriter Narrow font.
Internal Operations on the Default Template
The MIF doclet performs the following internal operations on the
default template. This is documented here for the purpose of helping
you understand how this template is used and why there are some
limitations on its use.
Parsing into styles, master pages and text flow - The MIF
Doclet parses the imported template into three parts:
(1) The styles section contains definitions of all styles (paragraph,
character, table, variables, cross-reference, numbering),
(2) the master pages section contains the master and reference pages,
and (3) the text flow section contains all of the rectangular text
blocks (the doclet discards all of the text content).
Next, it inserts these sections into the appropriate places in
the output stream (generated files). It then performs search
and replace operations described next.
If importing a custom template and the doclet fails to be
able to parse it properly into these three sections, it will
switch to the default template. This enables it go proceed
successfully, so that it generates some output that you can
at least inspect, rather than fail and stop.
Template for front matter (template-roman.mif) -
Enables the front matter to have roman numeral page numbering.
The MIF Doclet generates this template from
template.mif by copying it and modifying the page number
from arabic to lowercase roman numeral (by changing the MIF statement
<DPageNumStyle Arabic> to
<DPageNumStyle LCRoman>).
If the front matter is not roman numeral, it may because you are
using a custom title file set to arabic
page numbering.
The default front matter includes titlepage.mif and
contents.mif.
This file is saved to the mif
subdirectory.
Template for two-column index (template-indextwocol.mif)
- Enables the alphabetic index to be two columns. The MIF Doclet generates
the template template-indextwocol.mif from
template.mif by copying it and changing the number of
columns from 1 to 2 on master pages "Left", "Right" and "ChapterOpener-R".
This file is saved to the mif
subdirectory.
Custom FrameMaker Templates
If you want to customize your own book, you would typically
customize copies of the following two files:
If you want to further customize the title page, table of contents and
index (or customize these without altering the default template),
you could also customize copies of these three files:
In general, all files in the book are derived from the default template.
If the default template is not adequate
or appropriate for your purpose, you may want to use a custom
FrameMaker template. There are two ways to go -- both use the
-importformats
option to import the template (and are described at greater
length below):
- Modify a copy of the default template -
This is the most reliable approach, as it is
built off the default template, which the
MIF Doclet has been designed for and tested
with.
- Use your own FrameMaker templates -
By this, we mean using a template that is not
derived from the default template.
There are tradeoffs associated with this approach,
mainly that you may need to manually import your own
template if it doesn't work with
-importformats.
Whichever case you choose above, whenever you want to modify
the name of a style or definition applied to text
that the MIF Doclet generates, you must also:
- Modify a copy of the default stylemap file
stylemap.properties
This is described below under
stylemap file.
Modifying a Copy of the Default Template
If you want to alter the appearance of your document from the default format
and layout, the easiest wasy is to modify a copy of template.mif.
Here's an explanation of where to find it.
The MIF Doclet has the default template.mif
file built-in. Whenever you run the MIF Doclet, it writes a
copy of this file into the
mif
subdirectory of the destination directory (defined with
-d). You can copy the templates.mif
file from there. Name it whatever you want and put it
anywhere you'd like, but don't modify the original
without moving or renaming it. The original
will get overwritten the next time you run the MIF doclet.
The following are examples of things you might want to
change in your copy of the default template.
Acrobat Setup - The Acrobat Setup determines which headings appear
in the Acrobat Reader bookmarks. (To view the bookmarks, choose
View > "Bookmarks and Page" in Acrobat Reader.
The bookmarks are the table of content entries that appear in the
left frame.)
To set these headings, open the FrameMaker template, in the menus go
to Format > Document > Acrobat Setup. Move the headings
you want included to the left-hand list. (You can also set the Acrobat
Setup in the Print dialog box.) Bookmarks set this way are
not overridden by the Acrobat Setup in the printer settings file
passed in with the -print option.
Importing formats into the TOC and Index -
Note that using -importformats also imports formats
into the derived template-roman.mif and
template-2col.mif.
Use -contentsfile to create a custom table of contents file.
However, if you use -contentsfile to specify your own custom
table of contents file, -importformats will not import
formats into this file, in case you have properly formatted
it yourself (including roman numeral page numbers, as needed).
The same is true of -indexfile.
Using Your Own FrameMaker Templates
We do not guarantee or generally recommend using
-importformats with a FrameMaker template
that was not derived from the default template.
Instead, we recommend importing such templates by hand after the
MIF doclet run is complete. One distinct advantage of manual
importing is that you can import different templates for different
parts of the book (front, chapter and back matter).
This is not possible using -importformats.
(The MIF Doclet is designed to import a single template
into all files and parts of the book.)
The reason cannot guarantee any template will work
is due to the uncertainty that when the MIF Doclet performs
internal operations
they will proceed smoothly and successfully on the imported template.
However, if your template magically happens to conform
to the same unspecified structural requirements as our default
template, -importformats may just work.
The only way to know is to try it and check the console
messages for associated warnings or errors, and carefully
inspect that the output is as you desire.
The StyleMap File (stylemap.properties)
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 to modify a copy of this file only if you are going
to provide different names or mappings of FrameMaker styles.
The MIF Doclet provides a great deal of flexibility by allowing you
to rename the actual FrameMaker style names it generates. It does
this with a stylemap file.
The stylemap file maps style names internal to the MIF Doclet 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.
The stylemap.properties file maps the following
kinds of things:
- Paragraph style names, such as
ClassHead, ClassText-1
- Character style names, such as
Bold, Italic, Link
- Table names, such as
Members, MembersInherited and DocComment
- Cross-reference format names, such as
LinkXRef
- User variable names, such as
UserVariable1 and UserVariable1
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 use the stylemap file to
translate the style names into other languages.
Modifying a Copy of stylemap.properties
The stylemap.properties file lets you map existing
style names to new names. Here's an example that might be useful --
it illustrates how you would make the style of the first paragraph
of member text different from the second and subsequent paragraphs.
The default stylemap.properties file has
these two entries:
MemberText-1 MemberText # First paragraph of member description
MemberText-2 MemberText # Subsequent paragraphs of member description
The first mapping applies only to the first paragraph of
any member description (for field, constructor, method, or nested class).
The second mapping applies to all subsequent paragraphs for that member.
Notice they both map to the same FrameMaker style: MemberText.
Let's say you want the style for the only first paragraph to be
different by adding a "Description" subhead ahead of but on the same
line as the first line of the member description, like this:
Description: Called by the browser...
(This is similar to the
-descriptionhead option
for member descriptions, which lets you put "Description" on the previous
line, but it takes up more vertical space on the page.)
Setting this up is straightforward, requiring a new FrameMaker style
(step 1), redefining an entry in stylemap.properties
to make use of that style (steps 2 and 3), and then running the
MIF doclet with new options (step 4):
- Copy the default FrameMaker template
template.mif
to, say, template2.mif in the mif
directory. (You must run the MIF Doclet at least once to
generate a copy of the default template.) In this copy,
define a new paragraph style that defines the "Description"
heading -- let's call it MemberDescription.
To do this, go to Format > Paragraphs > Designer,
create a new style MemberDescription,
then choose "Numbering" from the popup, and type the
word "Description" in the "AutoNumbering Format" field,
choosing "Bold" as its character format.
- Copy the
stylemap.properties file.
First, some explanation on where to find it.
The MIF Doclet has the default stylemap.properties
file built-in. Whenever you run the MIF Doclet, it writes a
copy of this file into the
resources
subdirectory of the destination directory (defined with
-d). You can copy the stylemap.properties
file from there. Name it whatever you want and put it
anywhere you'd like, but don't modify the original
without moving or renaming it. The original
will get overwritten the next time you run the MIF doclet.
- Then modify the FrameMaker style names in the second column
of your copy of the stylemap file to names that match the
style names in the template you want to use.
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. In this example, modify the
MemberText-1 line as follows:
MemberText-1 MemberDescription # First paragraph of member description
NOTE - If you want to map to a FrameMaker style that
contains a space character, enclose the name in quotes,
such as:
MemberText-1 "Member Description" # First paragraph of member description
- You then run the MIF Doclet with these options,
assuming you named the file
stylemap2.properties:
-importformats path1\template2.mif
-stylemapfile path2\stylemap2.properties
where the paths are the absolute paths to these files,
or the relative paths from the current directory where
the doclet is started.
(As with any path, use a forward slash '/'
on Solaris and a backward slash '\' on Windows.)
Implementation Note - If you are modifying the MIF doclet source
code and adding internal style names, if those names are missing
from the left column of the properties file, they will just pass
through and get used directly in the template.
FrameMaker Template Q&A
Here are answers to some questions on how to alter the FrameMaker template.
Send more questions to
.
and we'll add them here.
How do I insert a tab character between the index item and the
item's page number?
- You'll have to use "-indexfile" with a custom index.
Copy index.mif to myindex.mif
and place it into your current directory from where you start
the doclet.
- Open the myindex.mif file in FrameMaker.
- Choose "View" > "Reference Pages".
- Find the paragraph with " 1, 2-3" text, with "SeparatorsIX" style applied to it.
- Replace the space ahead of the 1 with a tab character.
- Set right-aligned tab stops in the paragraph styles where page numbers can appear: Level1IX and Level2IX.
- Save the file and regenerate the index.
Each cross-reference shows a page number as a subscript number.
How do I add the word "page" ahead of the number?
- You'll have to use "-importformats" with a custom template.
If you don't already have one, copy template.mif to mytemplate.mif
and place it into your current directory from where you start
the doclet.
- Open mytemplate.mif and choose "Special" > "Cross-reference".
- Choose "Link & Subscript Page" in the Format popup menu.
- Click "Edit Format".
- Type "Page " between and <$pagenum[parity]>.
- Click "Change", then "Done".
- Choose whichever option makes sense and click "Update":
"Internal Cross-References"
"References to All Open Documents"
"References to All Documents"
It doesn't matter which one you choose if you re-run the doclet.
- Add "-importformats mytemplate.mif" to your MIF Doclet command
and re-run it.
Localizing or Customizing Static Text (mif.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 mif.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
Troubleshooting
Here are some tips and workarounds for error and warning messages
and problems that occur when running the MIF doclet. Please contact
us with other problems you find so we can include or fix them.
General Troubleshooting
- Bugs and Limitations
For the latest list of known bugs, please see
Changes and Bugs in MIF Doclet.
For the list of known limitations, see
Limitations.
- MIF Doclet Version Number
The version number of the MIF Doclet is the first line displayed in
the output stream. For more information, see
MIF Doclet Version Number.
- FrameMaker 5.5 / 6.0 compatibility - All the
files we supply are in FrameMaker 5.5, and can be run
successfully with 5.5 or 6.0. You can use one or the
other simply by adding its path to the PATH environment
variable. However, if you save some files as 6.0 and
then try to run the batch processor (fmbatch or
dzbatcher) using 5.5, it may hang.
- Using continuation characters with -docletpath -
The argument to
-docletpath must contain no spaces.
If the argument is very long, you may be tempted to place
a continuation character in it to continue it to the next line.
(The continuation character is \ on Solaris,
and ^ on Windows.) Make sure there is
no white space before or after the continuation
character and no leading white space on the next line.
- Troubleshooting the Batch File - Notice that
right before the batch processor is run, the command
is echoed to the screen, such as:
Executing: fmbatch /java/pubs/docs/mif/mif-to-fm.batch
The batch file mif-to-fm.batch contains
statements that the batch processor (fmbatch
or dzbatcher) runs. This file contains
operations for opening MIF files, importing formats
from templates, converting the files to FrameMaker,
updating the FrameMaker files (paginate, generate table
of contents and index), then saving and quitting.
If the batch file starts but hangs or doesn't complete,
copy the echoed command (mentioned above) to the command
line and add the verbose (-v) option:
fmbatch -v /java/pubs/docs/mif/mif-to-fm.batch
or
dzbatcher -v /java/pubs/docs/mif/mif-to-fm.batch
This will echo every command in mif-to-fm.batch
and display error messages, showing precisely which command
is causing the problem.
- MIF Files Are Not Platform-Independent - If you use the
MIF doclet to generate MIF files on Solaris (with
-batch
and -noexecutebatch), you cannot then simply
copy those files to Windows and use dzbatcher to run
the batch file and convert them to FrameMaker. Doing so results in
error messages such as
"Frame reports error -44: Cannot save file
[d:\mif\build\solaris\docs\fm\almanaclegend.fm]"
This incompatibility is likely due to path names being stored in
a platform-dependent manner.
- Links don't work
The symptom is that links are blue, but they are dead -- clicking
on them does nothing. One possible cause of this is that this line is
missing from your stylemap.properties file:
LinkXRef "Link & Subscript Page"
If you are using an old stylemap.properties, it may have
the following obsolete line:
Blue Underlined Blue Underlined
You should remove this line and replace it with the one above.
Error and Warning Messages
"javadoc: In doclet class com.sun.tools.doclets.mif.MIFDoclet, method start has thrown an exception java.lang.reflect.InvocationTargetException java.lang.NoClassDefFoundError: com/sun/tools/doclets/ClassDocCatalog"
This error indicates that you are running a version of Javadoc
earlier than 1.4.0 and the MIF Doclet is trying to generate the
constant values page. The <ConstantsFile> element
that generates this page is included in two test examples included
with the release:
test/example-bookfile/book-*.xml and
test/example-masterbook/subbook-*.xml.
The ability to get the values of static constant fields
was added in Java 2 SDK 1.4.0.
REMEDY: If you want to generate
the Constant Values page, you must upgrade to this version
or later. Otherwise, simply comment out or delete the
<ConstantsFile> element as follows
to allow the MIF Doclet to run properly:
<!--
<Chapter>
<ConstantsFile>
</Chapter>
-->
(This element should not have an "enabled" attribute, as it
does not work.) Setting "enabled" to false will not work.)
"javadoc: warning - cannot find class
dd.bizobj.Currency"
This warning means the source file for the specified
class cannot be found -- it should be included in
the packages or classes passed in on the command line,
and its path should be included in -sourcepath.
REMEDY: If you are passing in package names at the command line,
the remedy is to make sure its package (dd.bizobj)
is passed in, and that -sourcepath points to the
root of the package directory.
For more details, see -sourcepath.
If you are passing in class names at the command line,
then the remedy is just to make sure you pass in
Currency.java on the command line (prepended with the
appropriate path), as shown at
Documenting One or More Classes.
"javadoc: No package, class, or source file found
named ."
This error message can occur because -sourcepath is not
properly pointing to the root of the package directories. A more
obscure occurrence of this can happen on Solaris when using a
shell script containing continuation characters ("\")
-- any space characters following the backslash will cause this
error to occur.
REMEDY: The remedy is to search for and remove all such
spaces.
"Frame reports error 3"
or "Frame reports error -1"
When running the MIF Doclet, this cryptic "error 3" or "error -1" message
can occur:
Executing fmbatch utility on: docs/xxx.book-mif-to-fm.batch
starting maker ...
Frame reports error 3 "Error ???"
or
Executing fmbatch utility on: docs/xxx.book-mif-to-fm.batch
starting maker ...
Frame reports error -1 "Error ???"
This happens when fmbatch tries to write to a file
that is already open or locked. For example, this commonly occurs when
someone runs the MIF Doclet, opens up the FrameMaker book file api.book
to inspect the files, then runs the doclet again without first closing the
book file. In this case, the error occurs when trying to execute this batch
statement:
SaveAs d api.book.mif ../fm/api.book
REMEDY: To remedy this, close the FrameMaker book file and try again.
This error can also occur if a file is closed but locked, which
can happen if a FrameMaker file is open when your computer crashes,
which leaves its lock file undeleted.
A FrameMaker file is locked if its directory contains another file with
the same filename but with the extension .lck appended
to it. For example, if java.applet.fm is locked,
a small file named java.applet.fm.lck will exist in
that same directory. Immediately after a file is closed,
FrameMaker normally deletes that file's lock file. However,
if the file was closed improperly, say the computer
crashed, the lock file would still exist.
REMEDY: In this case, delete the lock file manually.
"Frame reports error 2: Cannot find the file named [C:\Documents]"
This error occurs when using dzbatcher and spaces exist in the
destination directory path or in any files generated by the MIF
Doclet. The entire error message appears like this:
Starting maker...
Connected.
Waiting for Frame results
Frame reports error 2:
Cannot find the file named [C:\Documents]
Make sure that the file exits.
The dzbatcher program does not support spaces in the paths
that appear in the batch file mif-to-fm.batch.
This is a dzbatcher bug that Sun cannot workaround.
REMEDY: To fix this problem, rename the directories or files
to not use spaces or use fmbatch (which does not run on
Windows).
"Frame reports error 8"
When running the MIF Doclet, this cryptic "error 8" message
can occur:
Executing: fmbatch /home/dkramer/docs/mif/mif-to-fm.batch ...
starting maker ...
+ Open /java/pubs/tutorial/mem4/exceptions/fm-output/mif/titlepage.mif
+ Open /java/pubs/tutorial/mem4/exceptions/fm-output/mif/template-roman.mif
Frame reports error 8 "Error ???"
This error occurs when a FrameMaker or MIF template file that is being
imported is size zero.
In MIF Doclet 1.5 Beta 1, the errant file should be displayed on the
line prior to this error message. (If not, make sure the -quiet option
is not set.) This error can happen due to either of two known conditions:
The template file can be size zero when the MIF doclet tries but fails
to generate template-roman.mif (for the table of contents) or
template-indextwocol.mif (for the index) from a user's custom template.
REMEDY: Look at the internal operations
that the doclet must perform to see which might be failing. You might
be able to fix it by looking at the MIF of your custom template and
adjusting it accordingly.
The error can occur when you are using -importformats to import
a template that is located in the destination mif directory. What happens
is the MIF Doclet writes over that file while it's open for import, resulting
in a file that is zero bytes in size.
REMEDY: To remedy this, move the template to any other directory
and change your -importformat option accordingly.
"method start has thrown an exception java.lang.reflect.InvocationTargetException java.lang.IndexOutOfBoundsException: Index: 0, Size: 0"
This can occur when setting the path in the -batch argument, such as:
-batch /net/irishmusic.eng/opt/local/framemaker,v6.0/bin/fmbatch
Contrary to the documentation, the path is not currently allowed
in the -batch option (and the error message is not helpful).
To workaround this, use -batch dzbatcher or
-batch fmbatch and let your PATH environment variable
specify the path to the batch program.
See
4652848
"The following Named Destinations were defined more
than once"
This error message occurs when fmbatch is running, and does not
appear to indicate any ill effects. The links appear to work
properly despite this error. The following shows the error message
in context.
Executing: fmbatch /java/pubs/ws/mifdoclettesting/jdkdocs2/mif-to-fm.batch...
starting maker ...
fmprintdr.ps: Using /usr/dist/local/share/doctools/frame5.5.6/fminit
maker: Using /usr/dist/local/share/doctools/frame5.5.6/fminit
maker: Starting FrameMaker 5.5.6. Copyright (c) 1986-1998 Adobe Systems Incorporated.
/java/pubs/ws/mifdoclettesting/jdkdocs2/book.tps:
% [ Warning: The following Named Destinations were defined more than once ] %
G1000.1024538
G1000.1024542
G1000.1024546
G1000.1024550
...
M1035.9.MemberHead.javalangreflectInvocationTargetExceptionInvocationTargetExceptionjavalangThrowabl
M1061.9.MemberHead.javaxswingJComboBoxisEditable
M1071.9.MemberHead.javaxswingJEditorPaneregisterEditorKitForContentTypejavalangString.javalangString
M1075.9.MemberHead.javaxswingJEditorPaneJEditorPaneAccessibleHypertextSupportHTMLLinkgetAccessibleAc
M1080.9.MemberHead.javaxswingJInternalFrameisClosed
M1080.9.MemberHead.javaxswingJInternalFrameisIcon
M1080.9.MemberHead.javaxswingJInternalFrameisMaximum
M1080.9.MemberHead.javaxswingJInternalFrameisSelected
M1104.9.MemberHead.javaxswingJOptionPaneJOptionPanejavalangObject.int.int.javaxswingIcon.javalangObj
REMEDY: None required.
"DocletAbortException"
In Solaris, we have found that some environment conflicts can prevent
dzbatcher from running, causing
DocletAbortException to be thrown.
REMEDY: A workaround is to
reduce your .cshrc file (or equivalent) to the minimum
settings, setting only the FMHOME environment variable,
and setting the path to "/bin", the FrameMaker bin location, and
the dzbatcher location:
setenv FMHOME /usr/dist/local/share/doctools/frame5.5.6
set path=(/bin /usr/dist/local/share/doctools/frame5.5.6/bin)
set path=($path /home/atuld/dzbatcher/SUNOS560)
"X is inconsistent in Y"
Here are two examples of many "inconsistent" errors that are possible:
"Color definition 15% Black is inconsistent in almanac.fm"
This message indicates that not all FrameMaker or MIF files have
the same color definition for "15% Black".
"Condition indicator for Comment is inconsistent in almanac.fm"
This message indicates that not all FrameMaker or MIF files have
the same condition definition for "Comment".
Such errors appear only when printing -- that is, when using the
-print (or <Print>) option.
The reason that errors for color and conditional text appear when
printing is because printing requires a single definition
for each color (under Print Separations) and type of conditional
text (which determines what to print or not print).
This error tends to happen if using your own custom pages
based on templates not derived from template.mif.
The custom pages might be for titlepage.mif,
contents.mif, index.mif,
almanac.mif or some other file.
REMEDY: To fix this, compare the definitions in all of
the MIF and FrameMaker files for the specified name. For
instance, "15% Black" should have the following color
definition:
<Color
<ColorTag `15% Black'>
<ColorCyan 0.000000>
<ColorMagenta 0.000000>
<ColorYellow 0.000000>
<ColorBlack 15.000000>
> # end of Color
The following definition is inconsistent -- it is mistakenly
defined to be 100% -- fixing this to be the same as above
would fix the problem and eliminate the warning message.
<Color
<ColorTag `15% Black'>
<ColorCyan 0.000000>
<ColorMagenta 0.000000>
<ColorYellow 0.000000>
<ColorBlack 100.000000>
> # end of Color
Similarly, the following two condition definitions for
the "Comment" conditional text are inconsistent:
<Condition
<CTag `Comment'>
<CState CShown>
<CStyle CAsIs>
<CSeparation 2>
<CColor `Red'>
> # end of Condition
<Condition
<CTag `Comment'>
<CState CShown>
<CStyle CUnderline>
<CSeparation 2>
<CColor `Red'>
> # end of Condition
- (Only in versions prior to 1.2Beta1)
"InvocationTargetException, NullPointerException"
The following exceptions can occur if you omit the standard doclet
path from the -docletpath option.
javadoc: In doclet class com.sun.tools.doclets.mif.MIFDoclet,
method start has thrown an exception
java.lang.reflect.InvocationTargetException java.lang.NullPointerException
- (Only in versions prior to 1.2Beta1)
"method optionLength has thrown an exception
InvocationTargetException NoClassDefFoundError"
An "optionLength" or "validOptions" error occurs when a command
line option is followed by the wrong number of arguments.
In versions A, B and C, this typically happened in the
-docletpath option when extending it to multiple
lines -- there must effectively be no white space on
either side of the colon. The space causes Javadoc to treat
the string as two arguments instead of one.
-docletpath /usr/local/mifdoclet/mifdoclet1.2/mif.jar: \ (incorrect)
^^^
Also do not use any leading white space on the line following the colon:
-docletpath /usr/local/mifdoclet/mifdoclet1.2/mif.jar:\
/usr/local/mifdoclet1.2/standarddoclet.jar \ (incorrect)
^^^^^^^^^^^^
This is what the correct command looks like:
-docletpath /usr/local/mifdoclet/mifdoclet1.2/mif.jar:\
/usr/local/mifdoclet1.2/standarddoclet.jar \ (correct)
The error message begins like this:
javadoc: In doclet class com.sun.tools.doclets.mif.MIFDoclet,
method optionLength has thrown an exception
java.lang.reflect.InvocationTargetException java.lang.NoClassDefFoundError:
com/sun/tools/doclets/mifoutput/ParaLine$Content at...
or
Javadoc: In doclet class com.sun.tools.doclets.mif.MIFDoclet, method
validOptions has thrown an exception
java.lang.reflect.InvocationTargetException java.lang.NoClassDefFoundError:
com/sun/tools/doclets/mifoutput/ParaLine$Content at...
- (Only in versions prior to 1.2beta1)
The characters `\\x0d` appear in the generated document. How do I
eliminate this?
This is often a cross-platform issue with version C and earlier.
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.
Bibliography
MIF Reference - Adobe System, Inc.
Provides a description of each MIF statement,
its syntax and examples.
Available online within FrameMaker by choosing
Help > Online Manuals > MIF Reference.
Doclet API - Sun Microsystems, Inc.
The API for customizing the output of Javadoc
Standard Doclet - Sun Microsystems, Inc.
A doclet for generating HTML output from source file doc comments
using Javadoc.
Please send errors, suggestions, comments and questions to:
.
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last modified: Sun Jul 31 11:40:20 PDT 2005
