$Id: README.txt,v 1.4 2008/12/23 10:40:06 h2b Exp $

Copyright (C) 2008 Hans-Hermann Bode, Berlin, Germany (h2b.de)

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License, version 2, as published by the
Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
details.

You should have received a copy of the GNU General Public License along with
this program.  If not, see <http://www.gnu.org/licenses/>.


CONTENTS

1 Introduction
2 Download
3 Installation
4.1 Usage (General Command Line)
4.2 Usage (Maven)
5 Problems with Internet Explorer


1 INTRODUCTION

This file, README.txt, is part of h2taglets. The current version of h2taglets
is 0.1.

h2taglets is a collection of Javadoc taglets that provide for mathematical
typesetting, bibliographical references and general numerical references.
It adds the following tags to Javadoc:

@math     includes mathematical formulas as HTML (with simple but convenient
          extensions), MathML or graphic
@label    produces a numerical label for cross-referencing
@ref      references that label
@biblio   builds a bibliography block
@cite     cites that block

They are intended to be used with the standard Javadoc doclet, at least Java
version 1.5.0 is required. The complete syntax of these tags and examples for
usage are included in the documentation of the corresponding taglets
(see http://h2b.de/sites/h2taglets/site/apidocs/index.html).


2 DOWNLOAD

You can download various zipped packages from http://h2b.de/projekte. In
particular they are:

h2taglets-0.1-doc.zip   documentation (also available online at
                        http://h2b.de/sites/h2taglets/site/index.html)
h2taglets-0.1-bin.zip   binaries
h2taglets-0.1-src.zip   sources

For use in your own documentation comments only the binaries are required.
Nevertheless, you should take a look at the documentation---either online or
in the zip file.


3 INSTALLATION

Unzip the downloaded package(s) into a directory of your choice. Note that the
three downloads are almost disjunct. Nevertheless, they will unpack into the
same subdirectory h2taglets-0.1. This is safe, since all overlapping files are
identical.

For general command-line use with javadoc no further installation is
required. If you plan to use h2taglets with Maven, however, you should install
the jar file from the binaries package into your local Maven repository; this
can be achieved by a command like this:

mvn install:install-file
  -Dfile=<path-to-jar-file>/h2taglets-0.1.jar \
  -DgroupId=de.h2b \
  -DartifactId=h2taglets \
  -Dversion=0.1 \
  -Dpackaging=jar \
  -DgeneratePom=true

(Of course, you must have Maven installed and configured before to do this.)
The <path-to-jar-file> has to be replaced by the path to the location where
the jar file has been installed. (With a standard installation as above this
is the subdirectory h2taglets-0.1 of the directory where you unzipped the bin
package.)


4.1 USAGE (GENERAL COMMAND LINE)

For use with Javadoc from the command line you have to provide these
additional arguments:

-tagletpath <path-to-jar-file>/h2taglets-0.1.jar
-taglet de.h2b.taglets.Registration

Of course, the <path-to-jar-file> has to be replaced by the path to the
location where the jar file has been installed before. (With a standard
installation as above this is the subdirectory h2taglets-0.1 of the directory
where you unzipped the bin package.)

A complete javadoc command could look like this:

javadoc -sourcepath <sourcedir> -d <targetdir> \
  -tagletpath <path-to-jar-file>/h2taglets-0.1.jar \
  -taglet de.h2b.taglets.Registration \
  <packagename>

Again, replace the parameters in angle brackets by appropriate values.


4.2 USAGE (MAVEN)

For use with Maven as a prerequisite you should install the jar file into your
local Maven repository as described above. Then include a reporting section
like this into your project's pom.xml (or complete an existing one
appropriately):

  <reporting>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <configuration>
          <taglets>
            <taglet>
              <tagletClass>de.h2b.taglets.Registration</tagletClass>
            </taglet>
            <tagletArtifacts>
              <tagletArtifact>
                <groupId>de.h2b</groupId>
                <artifactId>h2taglets</artifactId>
                <version>0.1</version>
              </tagletArtifact>
            </tagletArtifacts>
          </taglets>
        </configuration>
      </plugin>
    </plugins>
  </reporting>

Now, an 'mvn site' will produce the project's site including apidocs while
respecting the new tags of the h2taglets collection.


5 PROBLEMS WITH INTERNET EXPLORER

There are several issues related to Microsoft's Internet Explorer that may
arise when using the @math tag.

(a) It does not display all elements properly with respect to the HTML
<object/> tag. This may result in graphics not shown when included by @math.

(b) It has no built-in MathML capability. Thus, if you include MathML code by
@math, you should be aware that Internet Explorer users will have to install
some extension to their browser when looking at the resulting document.

(c) It may not have the complete font sets for all mathematical symbols. Thus,
if you include such symbols by @math, they may not be shown.

While (a) might be fixed in a future version of h2taglets (it's just a
question of generality and elegance of code vs. special treatment of all kinds
of outliers), (b) and (c) will not (since they happen to appear on the browser
side only). By the way, none of these problems have been observed (by me)
with Mozilla's Firefox 3.0.