Documentation Installation Instructions
This procedure describes how to install the JDK documentation that you have already
downloaded.
The compressed file that you download is called the documentation bundle.
- If necessary, concatenate all the pieces together
- Check the bundle size
- Where to unbundle your documentation
- Unbundle your documentation
- View the documentation
If you have installation problems, please send us email at: Website
Feedback. If the installation instructions could be clearer, please send
email to Documentation.
1.
If necessary, concatenate all the pieces together
If you have downloaded the documentation in pieces
instead of a single bundle, do this step:
Steps to concatenate the pieces together (below)
The final size should be the same as that given in the next step.
2.
Check the bundle size
Check to see that the complete file was downloaded:
jdk12-doc.zip 16,897,834 bytes
jdk12-doc.tar.gz 10,164,574 bytes
jdk12-doc.tar.Z 21,669,598 bytes
3.
Where to unbundle your documentation
By default, unbundling the JDK documentation creates a jdk1.2
directory with a docs subdirectory, putting all the documentation
inside that docs directory, as shown below.
You should install the JDK documentation into the same directory as
you install the JDK software (and can install them in either order).
This enables the links between the software and documentation to work.
- If using WinZip -- accept the default directory of
jdk1.2 .
- If using a command-line zip or tar tool -- you should
unbundle the documentation in the parent directory of
the jdk1.2 directory. For example:
- Windows: If your jdk1.2 directory is located at
C:\jdk1.2, then you should switch the current directory
to C:\ before unbundling the docs:
C:> cd \
- Solaris: if your jdk1.2 directory is located
at /usr/local/jdk1.2, then you should switch the current
directory to /usr/local/ before unbundling the docs:
% cd /usr/local/
4.
Unbundle your documentation
Unbundle the documentation using the appropriate utility:
winzip, unzip, gunzip,
pkunzip, uncompress, or tar. Your utility must support long file names.
Choosing a program to install the docs: The download bundles
have identical documentation content and differ only in the
compression format, so theoretically any bundle can be installed on
any OS with a program that handles that format. However, do not try
to install the COMPRESS tar or GZIP tar formats with
WinZip or other non-Solaris versions of tar. About 10 of the included
files have unbundled paths that are 100 characters or longer, and
these programs will not install them correctly. For more details, see
the
troubleshooting tip.
- For the WinZip program, run the program and accept
jdk1.2 as the default directory.
- For .zip files:
C:> unzip jdk12-doc.zip
Note: If you're using another tool that doesn't preserve
path names by default, be sure to specify that path
names be preserved. If you're using
pkunzip, for example, specify -d:
C:> pkunzip -d jdk12-doc.zip
- For .tar.gz files:
% gunzip jdk12-doc.tar.gz
% tar xvf jdk12-doc.tar
- For .tar.Z files:
% uncompress jdk12-doc.tar.Z
% tar xvf jdk12-doc.tar
Unbundling the documentation bundle creates a jdk1.2/docs/
directory containing your JDK documents, as shown below.
5.
View the documentation
Open the jdk1.2/docs/index.html page in a browser.
This is the front page and contents of the JDK documentation.
JDK Directory Structure
Installing the JDK software and documentation creates the following
directory structure. The directories shown in bold are installed
with the JDK documentation bundle.
jdk1.2
______________________|____________________________
| | | | | | | | | | | |
| README | LICENSE bin lib | include | src.jar | docs
| | | | | | | | |
README.html COPYRIGHT jre include-old demo |
__|__ | | |
| | |
bin lib |
| | |
|
_______________________________________|_
| | | | | |
index.html guide api tooldocs relnotes images
| | | | |
If you don't unbundle the documentation at the proper directory, the HTML
links from docs/index.html to the README, CHANGES, COPYRIGHT,
LICENSE, and demo files will be broken.
Steps to concatenate the pieces together
After downloading these files, follow the steps below
to join them into one.
Unbundle the documentation using the appropriate utility: winzip, unzip, gunzip or pkunzip.
Your utility must support long file names.
You need enough disk space for these files plus the resulting file.
jdk12-doc-a.zip
jdk12-doc-b.zip
jdk12-doc-c.zip
jdk12-doc-d.zip
jdk12-doc-e.zip
- Windows - Use
copy to join
the pieces into a single file:
C:\> copy /b jdk12-doc-a.zip + jdk12-doc-b.zip +
jdk12-doc-c.zip + jdk12-doc-d.zip + jdk12-doc-e.zip
jdk12-doc.zip
- Solaris - Use
cat to join
the pieces into a single file:
% cat jdk12-doc-a.zip jdk12-doc-b.zip jdk12-doc-c.zip \
jdk12-doc-d.zip jdk12-doc-e.zip > jdk12-doc.zip
The resulting concatenated file should be the same size as the
jdk12-doc.zip file as given in the
next step.
Troubleshooting the Doc Installation
- WinZip and other non-Solaris versions of tar do not properly unbundle
the Compressed tar (tar.Z) and GZIP tar (tar.gz) versions of the docs.
WinZip and Cygnus GNU tar are two such incompatible programs.
This problem occurs because about 10 of the included files have paths
(including filenames) that exceed 99 characters, and there is no
universal way of handling files of this length in the tar format.
If you're not on Solaris, use the zip format instead. If you have a version
of the jar tool, you can use that to unbundle the zip format.
WinZip does unbundle "tar" files, but not if they contain paths that
exceed 99 characters. Developers prefer to download the tar versions
because they are smaller than the zip version.
If you have downloaded a tar version and installed it with a non-Solaris program,
the files whose paths exceed 99 characters will be installed in the same
directory where you are expanding the tar package, which is the wrong
location, so links to them will be broken.
The JDK doc bundle contains the following files whose paths
(including filename) exceed 99 characters:
JComponent.AccessibleJComponent.AccessibleContainerHandler.html
JEditorPane.JEditorPaneAccessibleHypertextSupport.HTMLLink.html
JTableHeader.AccessibleJTableHeader.AccessibleJTableHeaderEntry.html
BasicFileChooserUI.ChangeToParentDirectoryAction.html
BasicInternalFrameTitlePane.PropertyChangeHandler.html
BasicTreeUI.SelectionModelPropertyChangeHandler.html
BasicInternalFrameUI.InternalFramePropertyChangeListener.html
BasicInternalFrameUI.BasicInternalFrameListener.html
BeanContextServicesSupport.BCSSServiceProvider.html
BeanContextServicesSupport.BCSSProxyServiceProvider.html
For the full, correct paths, see:
Correct Paths.
The result is that the path to these files is stripped off, and
they are installed in the jdk1.2 directory.
Workaround: Download the ZIP file and unbundle it.
(If on Windows, unbundle it with WinZip.)
Background: The original tar format supports a maximum path size of
99 characters. If you use Solaris tar, you will not see a problem,
because Solaris tar extends this format beyond 99 characters
but in a Solaris-only way. GNU tar has a different way of extending
the format, so is incompatible with the Solaris tar.
WinZip and Cygnus GNU tar 1.11.8 do not support the Solaris way.
We recommended that you use Solaris tar to extract the
archive, or use the jar tool or WinZip to extract the zip version.
|