Obtaining the Code

The source for XHTML Doclet is freely available on Sourceforge. The most up-to-date version can be obtained by checking the code out from the project Subversion repository. I suggest checking out only the trunk (active development) with the following command:

svn checkout https://xhtmldoclet.svn.sourceforge.net/svnroot/xhtmldoclet/trunk xhtmldoclet

This command creates a folder xhtmldoclet in the current directory. After you have a copy checked out, running svn update from within the checked out project directory will download and apply any changes that may have occurred since the last update.

GUI Subversion tools—such as TortoiseSVN and AnkhSVN for Windows, or Versions, svnX, and SCPlugin for Mac OS X—can also be used to obtain and manage a checked out copy.

If you're just interested in casually perusing the code, you may also browse the repository.

Building the Project

The project trunk includes an Ant build script (build.xml), which includes the following targets, among others:

  • ant compile — Compiles the source code and displays errors.
  • ant jar — Creates a doclet JAR file for usage with Javadoc.
  • ant javadoc — Creates Javadocs using the standard doclet.
  • ant newdocs — Creates Javadocs using XHTML Doclet.
  • ant stats — Creates statistics of SVN activity, project size over time, etc.
  • ant clean — Remove compiled classes, generated documentation, and stats.

To see all the documented targets in an ant build script, run ant -projecthelp from the directory containing the build.xml file.

Integrating with Eclipse

Eclipse is a powerful open-source IDE that is well-suited for Java development. It is used extensively for developing XHTML Doclet, and we highly recommend it. However, the hardest part of using it is usually getting it configured. To simplify the process, below are some instructions that should make it easy to get XHTML Doclet up and running in Eclipse.

Project Setup

There are several approaches for setting up an Eclipse project for XHTML Doclet:

  1. Import using the existing Eclipse project files

    Since the repository trunk already contains the .project and .classpath files used by Eclipse to store information about a project, this is ususally the most straightforward approach.

    Steps:

    1. Navigate to your Eclipse workspace directory, then check out the project trunk.
    2. In Eclipse, select File > Import... and choose General > Existing Projects into Workspace.
    3. Browse to the checked-out XHTML Doclet trunk (the directory containing src/, build.xml, etc.) and click Choose.
    4. Check the box for xhtmldoclet and click Finish.

    Notes:

    • This approach will show all the files and folders for the project in the Package Explorer.
    • Opting to delete the project will probably prompt complaints about read-only Subversion files.
    • If you check the code out into another location and select the option for copying the files to the workspace, Eclipse's version will get out of sync with the original.

  2. Create a new project from the Ant build file

    Eclipse can parse a build.xml file and create a project that uses the same structure and targets. It has an option to link to the original files, so everything stays in sync. (Eclipse modifies the files in the location where the build file resides.)

    Steps:

    1. Check out the trunk in a directory of your choice.
    2. In Eclipse, select File > New > Project....
    3. Choose Java > Java Project from Existing Ant Buildfile, then click Next.
    4. Browse to build.xml in the checked-out version of XHTML Doclet, click Open.
    5. Check the box for Link to the buildfile in the system, click Finish

    Notes:

    • This approach will show only the source directory, build file, and project libraries in the Package Explorer.
    • Since the project links to the checked-out copy, all changes stay in sync, and deleting the project is hassle-free.
    • This approach automatically configures the default build target as a run configuration. (See below.)

  3. Check out the project directly with Sublipse

    Subclipse is a plugin that provides support for Subversion within Eclipse. Subversion information is represented as text and icon badges on files and folders.

    Steps:

    1. Install Subclipse in your Eclipse installation.
    2. Select File > New > Checkout Projects from SVN.
    3. Select Create a new repository location and click Next.
    4. Type https://xhtmldoclet.svn.sourceforge.net/svnroot/xhtmldoclet and click Next.
    5. Select trunk from the hierarchy and click Finish.

    Notes:

    • Subclipse must be installed, which is a little more involved (but worth it).
    • Shows all project files and folders in the Package Explorer, just like option A.
    • Much easier to track changes and perform Subversion tasks visually.
    • Ideal for those taking an active part in development and committing changes.

Run Configurations

Run configurations allow you to easily run and debug Ant builds within Eclipse. They are also accessible from the toolbar, via the green play button with a red toolbox. To create or modify a run configuration:

  1. Choose Run > External Tools > Open External Tools Dialog...
  2. Click on Ant Build in the menu at left, then press the New button to create a configuration.
  3. Under Buildfile, click Browse Workspace..., click xhtmldoclet, select build.xml, and click OK.
  4. In the Targets tab, check the boxes you want to run for the configuration.
  5. Give the configuration a name (at top), then click Apply and Run.

The configuration now appears in the toolbar menu, and its output displays in the Console tab when run.

Code Style Profiles

Eclipse can format code by selecting a section of text or one or more files and selecting Source > Format. For consistency, all code for XHTML Doclet should be formatted using the same rules. For simplicity, you can download the applicable code style profiles. To apply these profiles, open Preferences, expand Java > Code Style, then select the sub-group to modify (listed below).

  • Code Templates (When creating new classes, methods, etc.)
  • Clean Up (Source > Clean Up)
  • Formatter (Source > Format)
  • Organize Imports (Source > Organize Imports)

For each category, click Import... then browse to and select the file to import. You can make the settings apply to all Eclipse projects if you like; to limit it to XHTML Doclet only, click on the Configure Project Specific Settings... link in the upper right corner, then select the project for which to modify settings. You'll have to check Enable project specific settings and select the profile from there, after which the profile in the Preferences dialog will be the default for all other projects. (Do this for each desired Code Style sub-group.)