Make sure that you have a recent version of a Java JDK installed and that your JAVA_HOME environment variable is set. This procedure has been tested with JDK 1.8.0. See Setting JAVA_HOME at the end of these instructions.
Clone the whole repository. Open a terminal window and run the following commands to get the whole Impala repository from Git and go to the docs folder:
git clone https://gitbox.apache.org/repos/asf/impala.git cd <local_directory> git checkout master cd docs/
Where master is the branch where Impala documentation source files are uploaded.
Clone only the docs directory. Open a terminal window and run the following commands to get only the Impala documentation source files from Git:
git init impala_docs cd impala_docs git remote add origin https://gitbox.apache.org/repos/asf/impala.git git sparse-checkout set docs/ git pull origin master cd docs/
You'll see only the ‘docs/’ sub-directory is downloaded.
Download the DITA Open Toolkit version 2.3.3 from the DITA Open Toolkit web site:
https://github.com/dita-ot/dita-ot/releases/download/2.3.3/dita-ot-2.3.3.zip
Note: A DITA-OT 2.3.3 User Guide is included in the toolkit. Look for userguide.pdf in the doc directory of the toolkit after you extract it. For example, if you extract the toolkit package to the /Users/<username>/DITA-OT directory on Mac OS, you will find the userguide.pdf at the following location:
/Users/<username>/DITA-OT/doc/userguide.pdf
/Users/<username>/DITA-OT.bash_profile. On Mac OS X, it is probably /Users/<username>/.bash_profile.<path_to_bash_profile>/.bash_profile file and add the following lines to the end of the file.# Add dita to path export PATH="/Users/<username>/DITA-OT/bin:$PATH"Save the file.
source <path_to_bash_profile>/.bash_profile.dita is in your PATH. A command like which dita should print the location of the dita executable, like:$ which dita /Users/<username>/DITA-OT/bin/dita
In a terminal, try dita --help. You should get brief usage, like:
Usage: dita -i <file> -f <name> [options]
or: dita -install [<file>]
or: dita -uninstall <id>
or: dita -help
or: dita -version
Arguments:
-i, -input <file> input file
-f, -format <name> output format (transformation type)
-install [<file>] install plug-in from a ZIP file or reload plugins
-uninstall <id> uninstall plug-in with the ID
-h, -help print this message
-version print version information and exit
Options:
-o, -output <dir> output directory
-filter <file> filter and flagging file
-t, -temp <dir> temporary directory
-v, -verbose verbose logging
-d, -debug print debugging information
-l, logfile <file> use given file for log
-D<property>=<value> use value for given property
-propertyfile <name> load all properties from file with -D
properties taking precedence
If you don't get this, or you get an error, see Setting JAVA_HOME and Troubleshooting at the end of these instructions.
The easiest way to build the docs is to run make from the docs/ directory corresponding to your git clone. It takes about 1 minute. This works because the make uses the provided Makefile to call dita properly.
Docs will end up in docs/build (both HTML and PDF).
In the directory where you cloned the Impala documentation files, you will find the following important configuration files in the docs subdirectory. These files are used to convert the XML source you downloaded from the Apache site to PDF and HTML:
impala.ditamap: Tells the DITA Open Toolkit what topics to include in the Impala User/Administration Guide. This guide also includes the Impala SQL Reference.impala_html.ditaval: Further defines what topics to include in the Impala HTML output.impala_pdf.ditaval: Further defines what topics to include in the Impala PDF output.Run one of the following commands, depending on what you want to generate:
To generate HTML output of the Impala User and Administration Guide, which includes the Impala SQL Reference, run the following command:
dita -input <path_to_impala.ditamap> -format html5 \ -output <path_to_build_output_directory> \ -filter <path_to_impala_html.ditaval>
To generate PDF output of the Impala User and Administration Guide, which includes the Impala SQL Reference, run the following command:
dita -input <path_to_impala.ditamap> -format pdf \ -output <path_to_build_output_directory> \ -filter <path_to_impala_pdf.ditaval>
Note: For a description of all command-line options, see the DITA Open Toolkit User Guide in the doc directory of your downloaded DITA Open Toolkit.
Set your JAVA_HOME environment variable to tell your computer where to find the Java executable file. For example, to set your JAVA_HOME environment on Mac OS X when you have the 1.8.0_101 version of the Java Development Kit (JDK) installed and you are using the Bash version 3.2 shell, perform the following steps:
Find your .bash_profile. On Mac OS X, it is probably /Users/<username>/.bash_profile. Edit your <path_to_bash_profile>/.bash_profile file and add the following lines to the end of the file.
# Set JAVA_HOME JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_101.jdk/Contents/Home export JAVA_HOME
Where jdk1.8.0_101.jdk is the version of JDK that you have installed. For example, if you have installed jdk1.8.0_102.jdk, you would use that value instead.
Open a new terminal, or run source <path_to_bash_profile>/.bash_profile.
Test to make sure you have set your JAVA_HOME correctly:
Open a terminal window and type: $JAVA_HOME/bin/java -version
Press return. If you see something like the following:
java version "1.8.0_101" Java(TM) 2 Runtime Environment, Standard Edition (build 1.8.0_101-b06-284) Java HotSpot (TM) Client VM (build 1.8.0_101-133, mixed mode, sharing)
Then you've successfully set your JAVA_HOME environment variable to the binary stored in /Library/Java/JavaVirtualMachines/jdk1.8.0_101.jdk/Contents/Home.
Note: The exact version and build number on your system may differ. The point is you want a message like the above.
If you're trying to use DITA-OT to build docs and you get an exception like this
java.lang.NoSuchMethodError: org.apache.tools.ant.Main: method <init>()V not found
at org.dita.dost.invoker.Main.<init>(Main.java:418)
at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:57)
at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
at java.lang.reflect.Constructor.newInstance(Constructor.java:526)
at java.lang.Class.newInstance(Class.java:379)
at org.apache.tools.ant.launch.Launcher.run(Launcher.java:279)
at org.apache.tools.ant.launch.Launcher.main(Launcher.java:109)
... your CLASSPATH may be interfering with DITA-OT‘s ability to find the proper Ant. While you’re free to fix the CLASSPATH yourself, it may be easier just to run
unset CLASSPATH
and try again. This will use the libraries and Ant provided by the DITA-OT package.