The Eternal Eclipse Mac OS

Abstract

This document explains how to quickly start working with DocBook using your Eclipse Web Tools Platform (WTP) environment. WTP is required only for the XSLT features it provides. This article covers Mac, Linux, and Windows.

If your external hard drive is read-only on your Mac due to its NTFS file system, you can fix it by reformatting the device to a Mac-compatible format with Mac Disk Utility. Before that, remember to back up your external hard drive quickly with data backup software since the formatting will erase all the files on the device. Use Mac OS X 10.5 Leopard (with all software updates) on a Core 2 Duo Intel Mac, with Java Preferences set to use Java SE 6 as the default Java version, and use the 64-bit Cocoa version of Eclipse 3.5.1. Use Mac OS X 10.6 Snow Leopard on an Intel Mac, and use the 64-bit Cocoa version of Eclipse 3.5.1 note, I have not specifically tested this. Share your videos with friends, family, and the world.

Table of Contents

1. Introduction
2. Getting Files
2.1. DocBook Stylesheets
2.2. Formatting Objects (FO)
2.3. OFFO Hyphenation
3. Installing DocBook Files
3.1. Mac OS X
4. New Eclipse Workspace
5. Configuring a New DocBook Project
6. External Tools Configuration
6.1. Main Tab
6.2. Refresh Tab
6.3. Build Tab
6.4. Targets Tab
6.5. Classpath Tab
6.6. Copy Configurations
7. References

For this version of the article, I'm going to assume you have some reason tolearn DocBook rather than try to provide a motivation. But just in case youstumbled on this document expecting an office suite replacement for productssuch as MS-Office, OpenOffice or LibreOffice, stop now. DocBook is not aWYSIWYG product. It has a considerable learning curve and should only beused by propeller-heads.

But perhaps you're already interested in DocBook but are wondering why useEclipse to produce DocBook documents. I found Eclipse helpful for DocBookusage for the following reasons.

  • Eclipse has built-in support for stylesheet transformations. You have to make sure you download the right edition (the J2EE edition is a safe bet).

  • Eclipse has support for developing and running Ant scripts. You can get by without script support for your first few toy documents. But as you learn about the various parameters supported by the output configuration, provding the parameters via a command line becomes unwieldy.

  • Eclipse has spell checking support within its XML editors.

DocBook is basically a set of stylesheets that convert our content-centricXML source files into a desired format. So acquiring DocBook amounts toacquiring these stylesheets.

The DocBook stylesheets themselves are located at the following link.

Download the latest version in an archive format suitable for your OS.

If you want to generate PDF files, then there are a few more downloads. DocBookdoesn't generate PDF files directly. Rather, it generates an XML documentstructured as Formatting Objects, or FO. A separateprocessor developed by an Apache project calledFormatting Object Processor (FOP) takes the FO outputfrom DocBook and produces a PDF file.

Figure 1. Generating PDF from DocBook


FOP may be downloaded from the Apache FOP project.

Choose the binary download. You'll be asked to choose a mirror. On themirror site, choose the binaries folder and download the latest stabledistribution in the archive format supported by your OS.

FOP uses a hyphenation toolkit that is part of the OFFO project. The binaryis downloaded from SourceForge.

Download the file offo-hyphenation-binary_v2.0.zip.

Installing DocBook files pretty much amounts to unarchiving them. Butit pays to plan things up front to ease the upgrade process when newversions of the stylesheets are released. The schemes described inthis article differ slightly by OS.

Where you place files is somewhat arbitrary. This section is simplywhere I place them. Feel free to override these guidelines with anypreference you may have.

I configure the DocBook related stylesheets in/usr/local/share. One musthave admin rights to set up here. If you don't have adminprivileges, you may follow these steps substituting a locationunder your user directory.

  1. Expand the DocBook stylesheets into /usr/local/share. The name of the directory created by expanding the archive should contain the version number of the stylesheets.

  2. Create a soft link named docbook that points to the directory just created by expanding the archive.

    Afterward, your directory should look similar to this.

  3. Expand the FOP and OFFO archives into the /usr/local/share/java directory. For the FOP directory, create a soft link as was done in the previous step. This is not necessary for the OFFO distribution since we are simply poaching its library, not referencing it. The /usr/local/share/java directory should look similar to this.

  4. Copy fop-hyph.jar from the OFFO installation to the fop/lib directory. (Or you can simply hard link to it.)

This completes the file system set-up for Mac OS X.

To configure a new Eclipse workspace for DocBook projects, installthe XML/XSL templates from the Starter Kit to quicken the creationof new source files. These are located in thetemplatesfolder of the Starter Kit.

  1. Import the DocBook Starter Kit as a plain Eclipse project or simply have the files somewhere handy.

  2. Open Windows → Preferences of your Eclipse workspace. As shown in Figure 2, there are two templates to import.

  3. First choose XML → XML Files → Editor → Templates and import templates/xml/docbook-new.xml from the Starter Kit. This will create two new creation templates for XML files named DocBook Master and DocBook Section as shown in Figure 2.

  4. Then choose XML → XSL → Templates and import templates/xsl/customization-pdf.xml from the Starter Kit. This will create a single creation template for XSL files named DocBook Customization.

    Figure 2. Importing XML/XSL Editor Templates


  5. To use Xalan for XSL processing run configurations, navigate to XML → XSL → Java Processors as shown in Figure 3 and choose Xalan from the list.

    This is only meaningful if you intend to execute the DocBook stylesheets directly from an Eclipse run configuration. If you invoke the stylesheets from an Ant script as described in the next section, the Xalan processor is specified in the Ant script.

    Figure 3. Choose Xalan for XSL Processing


We need to configure our DocBook project dependencies independentof where we install them on our file system.Since we usually expect to source-control ourDocBook source and build-scripts, we need to organize our Eclipseworkspace so that file system and OS dependencies don't creep intosource-controlled artifacts. This is accomplished on most platformswith soft links and build links.

  1. Create a new project to hold the DocBook source. The type can be a simple project.

  2. Create a directory named softlinks.

  3. Make the DocBook and FOP installations appear to reside in our project under softlinks directory. Whether copies of those directories need to reside there depends on the OS platform. Linux and OS X support directory soft links. Windows does not. The Eclipse platform itself supports links for files, but not directories.

    Linux and OS X users can use the following technique.

    1. Open a terminal to the softlinks directory.

    2. Run the following command.

    3. Run a similar command for the FOP folder.

      ln -s {path to FOP installation} fop

    Windows users must actually copy these folders into their Eclipse workspace under the softlinks directory. This is not a very attractive solution. I wasn't able to make the any of the following work in its place.

    • Windows Shortcuts - On a Windows desktop or file explorer, a Windows shortcut looks like the real thing. But it's actually a file with an .inf extension. In the Eclipse workspace, we get docbook.inf and fop.inf.
    • Eclipse Links - Eclipse provides a linking mechanism to refer to files and directories outside the workspace. Unfortunately, this linking information is stored in the .project metadata file that Eclipse uses for a project, not in workspace metadata. Thus it would also become source controlled and then imposed on others.

  4. Copy the build folder of the Starter Kit into your new project. This includes a build-core.xml that defines source dependencies and sets a few global properties. The other files reference build-core.xml and generate specific output formats.

  5. Create the following folders in your new project.

    • images - used for storing image files.
    • out - stores generated output for each of the output types.
    • src - the source for your document content.

  6. In most cases, you will want to create a subdirectory of out for each output type. These directories contain files that control the presentation of your documents. (The src directory determines the content). If you generate PDF output, a pdf folder would contain the customization layer. If you generate HTML or EPUB output, the html or epub folder would contain the your CSS files.

You're ready to start writing your DocBook source!

Eclipse uses an external tools configuration to executeexternal tools. One of the most common external tool is theAnt build script. Several Ant scripts are included in the Starter Kit. The most convenient way to execute these scriptsis to execute them from a external tool configuration thatstores its parameters and dependencies in a single place andis invoked at the click of a button.

The external tools configuration dialog is invoked from Run → External Tools → External Tools Configurations.Right-click on Ant Build and select New. This panel has severaltabs to be configured. These are described in the sectionsbelow.

The Eternal Eclipse Mac OS

In the main tab enter the name of the build. A good convention tofollow is a short name for the document followed by the format ofthe build. In the exampleshown in Figure 2the configuration for the HTML build of this document is named'DocBook HTML.'

Figure 4. External Tools Configuration - Main Tab


The Buildfile field holds the location of the Ant script.The simplest way to complete this field is to click the button and navigate to<project>/builds/build-html.xml.In a similar way complete the Base Directoryfield. Set it to the root of the workspace.

Eclipse often caches elements of its workspaces to improve performance.Changes that an external tool makes to the file system are not immediatelynoticed by the Eclipse workspace. This can always be remedied manuallyby selecting an altered resource (or folder containing it) and pushingthe on your keyboard. This tab provides foraccomplishing this automatically. Several operations are available.The trick is to only refresh as much as you need since the more you askto be refreshed, the longer it takes. In our case, we want to refreshthe out directory since that iswhere our build scripts place their artifacts.

Check the box marked .We won't necessarily have a resource selected when the build script isrun, so it's safest to choose and click its button. Choose the out directory.

Figure 5. External Tools Configuration - Refresh Tab


Uncheck the box. In this case,the Ant script is doing all the necessary building. No workspace buildsare necessary.

An Ant script often has several targets that representthe production of some artifact. This panel allows one to choose a particularone. In the example shown in Figure 6,the box is selected. As it happens,This task declares a dependency on and. So those get built, too.

Figure 6. External Tools Configuration - Targets Tab


The button shows an error marker because itit is defined in a separate Ant script calledbuild-core.xml that is referenced by all the otherscripts. The Eclipse Ant editor is not yet smart enough to followrelationships across files. Fortunately Ant itself is.

This is the trickiest one. We need to include all the JARs that DocBookwill need to parse and transform DocBook source. The Xerces and Xalanlibraries can be downloaded from Apache'sXalanandXercessites.But since they are also included with the Eclipse distributions,it's easy just to reference them from the Eclipse plugin directory.Select theUser Entries root element in the list and on theright click the .Navigate to the pluginssubdirectory of your Eclipse install root and select thefour files in Figure 7 thatbegin with org.apache.x.

Figure 7. External Tools Configuration - Targets Tab


The DocBook Xalan extensions, xalan27.jar, are in theextensions subdirectory of theDocBook installation.

Creating the external tool configuration isn't that hard if you know whatyou're doing. But it's easy to forget if you haven't done it in a while.After you've followed these instructions once, it's easier to copy anexisting configuration than to create a new one from scratch. You'llchange the build file and choose different build targets. But theclasspaths will stay the same.

This will be demonstrated by creating an exernal tools configuration fora PDF build. Open the External Tool Configurations as before. Rightclick the DocBook HTML entry and selectDuplicate. This creates a new entrycalled DocBook HTML (1). It has most of thesettings you already need. Make the following changes.

  1. Change the name to DocBook PDF.
  2. Change the build fil to build-pdf.xml.
  3. Choose pdf in the Targets tab.
  4. Click the button to test.

A similar process can be used for creating an EPUB build. Also, the same techniquecan be used for builds of other DocBook projects, not just different renderingsof the same DocBook project. Just add these extra steps.

  • On the Main tab, select the new project for the Base Directory field.
  • On the Refresh tab select the new out folder for the new project.

[1] DocBook: The Definitive Guide, April, 2012. . Online: http://docbook.org/tdg51/en/html/

Eclipse On Mac

[2] DocBook XSL: The Complete Guide, Fourth Edition, September, 2007. . Online: http://www.sagehill.net/docbookxsl/index.html

Google uses cookies and data to:
  • Deliver and maintain services, like tracking outages and protecting against spam, fraud, and abuse
  • Measure audience engagement and site statistics to understand how our services are used
If you agree, we’ll also use cookies and data to:The eternal eclipse mac os x
  • Improve the quality of our services and develop new ones
  • Deliver and measure the effectiveness of ads
  • Show personalized content, depending on your settings
  • Show personalized or generic ads, depending on your settings, on Google and across the web

The Eternal Eclipse Mac Os Catalina

For non-personalized content and ads, what you see may be influenced by things like the content you’re currently viewing and your location (ad serving is based on general location). Personalized content and ads can be based on those things and your activity like Google searches and videos you watch on YouTube. Personalized content and ads include things like more relevant results and recommendations, a customized YouTube homepage, and ads that are tailored to your interests.

Eclipse Download Mac Os X

Click “Customize” to review options, including controls to reject the use of cookies for personalization and information about browser-level controls to reject some or all cookies for other uses. You can also visit g.co/privacytools anytime.