You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session.
Transforms DITA XML into PDF with the DITA Open Toolkit, Eclipse, Apache Ant, Apache FOP, SaxonHE, XSL
Notifications You must be signed in to change notification settings
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Go to fileAnd then come train in the REAL DOJO and reach your highest potential, become faster, stronger and more powerful. JEDI MASTER LEVEL. .
So now that you are the new Java Chuck Norris on the block, come and let's build.
First you should check if Java is already installed on your system.
In a terminal type the following commands:
If Java is installed you will see the Java help message like the image below.
If Java is not installed you need to install the Java Development Kit (JDK) as Eclipse needs Java to run so you should first read the Java Platform, Standard Edition Installation Guide
Choose the JDK version for your Operating System.
If it's installed you can read up about Java more by typing:
In the box near top labelled "Try the Eclipse Installer", click on "64 bit" under "Mac OS X".
Download Eclipse installer application.
Before you install Eclipse you should check the checksum of the Eclipse file.
Depending on which type of checksum you choose: MD5, SHA1, SHA-512 the commands are slightly different:
First you should click on the checksum type in the image below:
I used SHA-512 so the in a terminal in the directory or folder where you downloaded the Eclipse package to, the command to type would be:
You should check the output of the shasum command matches what's displayed on the Eclipse website for the type of checksum you choose. You can select the text in the terminal and then copy it and then find it on the Eclipse website.
For more information on the shasum or md5 command open a terminal and type:
Use the up and down arrows on the keyboard to navigate through the man page documentation.
To exit from the man pages type: q
Unzip resulting download (eclipse-inst-mac64.tar.gz) by double-clicking on it if downloader did not already unzip it.
Run "Eclipse Installer" application.
Choose "Eclipse IDE for Java Developers" option. (Other options and Eclipse modules are not necessary for this build.)
This option allows you to specify an "Installation Folder." The default option may be a folder within your individual directory.
It will be more useful to change this and install Eclipse within a directory titled "Eclipse" within the system's main Application directory.
Click on the folder icon to navigate to the Applications directory and create an "Eclipse" target sub-directory before installing.
Then click the "Install" button.
You will be presented with the Eclipse Foundation Software User Agreement, so click "Accept Now" after reading it.
The installation process may take a few minutes and you will be presented with a green "installing" loading bar style indicator.
When Eclipse has finished installing you will be presented with the "Launch" green button.
Launch Eclipse for the first time. Doing so will ask you to Select a "workspace." The default option "/Users/[your username]/Documents/workspace" will work fine.
Quit Eclipse for now.
The build's repository is found within GitHub, and the "GitHub Desktop" application will allow you to clone and work on the build more easily, while retaining a link to the primary source, and thus obtaining updates and having the option to submit modifications which could be candidates for inclusion. GitHub Desktop is currently available for both OS X and Windows.
Click on the "Download GitHub Desktop" button.
Unzip the resulting file: GitHub Desktop 216.zip
This expands to: GitHub Desktop
Move this to your system's Applications directory.
Switch your Eclipse workspace to the parent of the folder you cloned into
Then go -> File -> New -> Java Project -> click next
Enter 'dita-to-pdf-with-eclipse' in the Project Name field
Un-check location checkbox and enter in the parent folder of the project. In project layout select -> 'Use project folder as root for sources and class files' radio button and then click next.
On the next screen just click 'Finish'
You must add the JAR files from DITA-OT to Ant inside Eclipse. Go Preferences -> Ant -> Runtime -> Classpath tab -> click Global Entries -> click Add JARs -> navigate to 'libs/dita-ot-2.2.2/lib' and add all the JAR files from that directory. Make sure to click Apply and then click Ok.
Right click on build.xml and select -> Run As -> Ant Build -> (first one)
This should run and build and use as input both the DITA XML in the 'dita-test-files/debrief/' folder and the three ditamap's from the 'libs/dita-ot-2.2.2/samples' directory and will produce four PDF's in the 'output' sub folders 'output/debrief/pdf' and 'output/samples/pdf' folder.
Transformation and rendering (printing) occur in this step and the 'info.debrief' custom DITA-OT plugin produces a custom designed PDF via the DITA-OT base libraries, an XSL - Formatting Objects Processor (FO Processor) and the transformation engine SaxonHE. The other plugin 'sample' is a vanilla plugin with very little customization that makes the three sample PDF's.
I used Apache FOP 2.1 for the FO Processor and Saxon for the transformation engine that came bundled with DITA-OT 2.2.2.
Plugins are placed in the DITA-OT plugins directory. You can see the plugin I built in this directory named 'info.debrief' and the auto built vanilla plugin named 'sample'.
When ready a plugin must be integrated into DITA-OT using Apache Ant. I built this project using OS X and I installed Ant through Homebrew.
To integrate a new plugin on the command line from inside the root DITA-OT folder it would be -> ant -f integrator.xml
You can also run the integrator inside Eclipse as an Ant build by right clicking on '/libs/dita-ot-2.2.2/integrator.xml' and selecting -> Run As -> Ant Build and this should integrate the plugin with the toolkit.
Every plugin has a 'transtype' -> the two transtype's are 'debrief' and 'sample'
PDF Plugins are comprised of some XML config files, some artwork and some custom XSL (XSLT/XSL-FO/XPath) code DITA-OT provides that base XSL code that you 'override' with your custom work.
The two main files that configure plugins are plugin.xml and integrator.xml which should be in the root of the plugin folder. The 'cfg' folder contains the rest of the customization.
Custom XSL can be placed in two XSL files both named custom.xsl. I placed all the custom code at 'libs/dita-ot-2.2.2/plugins/info.debrief/cfg/fo/xsl/custom.xsl' for this project. The other file is seen in the adjacent 'attrs' directory.
Placing the custom code only in these two files follows best practice techniques on how to build a DITA-OT PDF plugin.
Homebrew is an amazing package management system for OS X that installs the stuff you need that Apple didn't.
A made a video on Homebrew which runs for under minute that shows the typical brew update command.
If you install Homebrew you should try to run brew update daily.
Once you have installed Homebrew you can run through the basic commands below.
Before using Homebrew you should ensure it's up to date. Run the next command:
