# GNU texidoclet

## Table Of Contents

1. Introduction
   - What is TexiDoclet?
   - Why use the info format?
   - How do I get started?
2. Requirements
3. Download
4. Installation
5. Configure
6. Usage
7. BUGS
8. History
9. TODO

## 1. Introduction

### What is GNU TexiDoclet?

GNU TexiDoclet is a system for creating info pages from Java source documentation. It is part of the GNU Classpath project, however it can also be used as standalone doclet used with any Java-compatible platform.

You can use TexiDoclet to create API documentation in info format for any set of Java packages (including classpath). The latter will reproduce the full Java API documentation for use on text-only displays, or for integrating it into the GNU Emacs online help facility.

TexiDoclet also includes an Elisp package which adds context-sensitive help features to GNU Emacs.

Note: This is alpha software. You should not use TexiDoclet in a production environment, because it has not yet been tested for reliability. Also, see Bugs for a list of currently missing features.

### Why use the info format?

Although the info format is raw text with nearly no formatting or highlighting, using the info version of the Java API documentation can have a number of advantages even on graphical displays - especially if you are using GNU Emacs:

- Because it is text-only, info is pretty fast.
- You can easily navigate through info pages using only the keyboard - which doesn't hold true for most HTML browsers available today, where you always have to grab the mouse or tab the focus.
- You can use all the powerful Emacs facilities to browse the documentation (e.g. incremental search, regular expressions, bookmarks).
- You can copy documentation fragments (like the definition of a method you want to overload) easily using the keyboard, again having all Emacs facilities right at hand, such as the ring buffer.
- You have no frames in info, but you can use the Speedbar contained in recent Emacs distributions for the same purpose [not tested as yet].

### How do I get started?

- Check the Requirements section and download/install any missing tools.
- Download and unpack the TexiDoclet package.
- See section Configure for further instructions.

### Thanks!

TexiDoclet was originally written as a standalone doclet by Julian Scheid and was contributed to the GNU Project as part of GNU Classpath.

## 2. Requirements

In order to use TexiDoclet, you need the following software installed:

- A Java platform 1.2 or better. The intention is to be able have TexiDoclet work first and foremost with GNU Classpath and other completely free toolchains (with gjdoc we are 99% there!) although it can be used with non-free VMs.
- GNU Make and GNU makeinfo. Note: makeinfo is contained in the GNU texinfo package.
- A Unix environment:
  - `bash` and the standard commands like `cp` are essential
  - `which` and `awk` are required for checking the setup
  - `gzip` is used to compress the info pages.

Makeinfo is required to convert the texinfo source into the info format. If you only need the texinfo source, you don't need makeinfo. Unix users will probably find a makeinfo preinstalled on their system. Windows users can find free precompiled binaries on the Internet (look for the Texinfo package).

Note: There are some 16-bit makeinfo binaries available online, but they won't work. You need to look for an up-to-date 32-bit binary.

GNU Make is required because if you want to generate the full standard Java API documentation, each package must be processed individually. The Makefile works with patterns to process the packages individually and merge the results.

Again, Unix users will find Make preinstalled. Windows users can find precompiled binaries on the Internet for free.

Note: Use only GNU Make - you will probably get into trouble if you try to use a different Make tool, because the TexiDoclet Makefile uses some GNU-specific features.

Tip: Configuring TexiDoclet is much easier if you make sure that all utilities (including the Java tools) are on your system search path.

TexiDoclet has been tested on the following systems:

Operating System | JDK | Other
Linux kernel 2.2.16 on Intel / Red Hat 7.0 distribution | Sun JDK 1.2.2 | GNU bash 2.04.11 GNU Make 3.79.1 GNU makeinfo 4.0 GNU Emacs 20.3.1
Linux kernel 2.2.9-27mdk / Mandrake distribution (thanks to Owen Lydiard for the report) | JDK 1.3 | GNU make 3.77 makeinfo (GNU texinfo) 4.0 GNU Emacs 20.3.1
As of the date of this document, no other configurations have been tested. If you install TexiDoclet on a different system, be it successful or not, please contact the developers so that this list can be extended.

### 3.1 Tool download locations for Windows users [untested]

Although the present version of TexiDoclet has not been tested on Windows, a previous incarnation was working using the following: Windows 98 / Sun JDK 1.3 RC2 / Cygwin B-20 (GNU bash 2.02.1) / GNU Make 3.78.1 / GNU makeinfo 1.68 (GNU texinfo 3.12) / GNU Emacs 20.6.1

Here are a few URLs for getting the Windows ports of the required software:

- The Cygwin project offers the most sophisticated port of Unix utilities for free download. Their "full" package includes a Bash and a full-featured Unix environment (including `grep`, `less`, `awk` and other useful commands.) With regard to TexiDoclet, only GNU `make` and `makeinfo` are missing.
- tertius.com contains a link to a Windows port of the texinfo package, including the required `makeinfo` tool. It also includes a standalone info viewer.
- Refer to the GNU Make homepage and to http://ftp.gnu.org for downloading the GNU Make binaries for Windows.

## 3. Download

The old (pre-GNU) version of TexiDoclet is still located at our old development site on sourceforge and is available from SourceForge. This (old) 0.5 version is provided purely as a convenience, and will soon be replaced by a new version . Subsequent releases will be made available at via the GNU ftp site (http://ftp.gnu.org/pub/gnu/).

The package includes an autoconfiguration system, the full source code, and additional Emacs add-ons. It unpacks into a separate directory named "`texidoclet-(version)`".

If you want to take a look at TexiDoclet's output first, here is a sample (32 K gzipped tar). It's the converted `info' docs for the TexiDoclet API (please note that the package name `gnu.texidoclet` is now obsoleted by `gnu.classpath.tools.doclets.texidoclet`) itself. [To view run the standalone `info` viewer: `info -f texidoclet.info`.]

## 4. Installation

Please note the following instructions relate purely to the old 0.5 version of GNU texidoclet, which is currently the only release

In order to install TexiDoclet, you should unpack it to a location of your choice. TexiDoclet will unpack into a separate subdirectory, which contains the following files and directories:

`Makefile` |  | the TexiDoclet main Makefile.
`COPYING` |  | the GNU public license (Version 2)
`etc/` |  | contains Makefile template for generating the docs for Sun's code.
`lisp/` |  | contains add-ons for enabling context-sensitive help in Emacs.
`source/` |  | contains the full Java source code for TexiDoclet

After you have unpacked the archive, you should configure TexiDoclet as described in the following section, Configure.

## 6. Configure

Please note the following instructions relate purely to the old 0.5 version of GNU texidoclet, which is currently the only release

[Taken from the `README` file in the distribution]

    Installation:
    ============

    1. The usual GNU autoconf procedure applies:

       ./configure
       make

       Read the generic INSTALL file for the details.

    2. Extra texidoclet-specific options for `configure':

       `--with-jdkdir=DIR'

        DIR specifies the location of the JDK (if it's not on the PATH)

       `--with-javadocjar=FILE'

       Use FILE as jar file with javadoc support.

    3. This will generate the jar file in source/TexiDoclet.jar.  You can
       choose to run "make install" at this point, although this is not,
       strictly speaking, necessary.

    4.  To see an example of the invocation of TexiDoclet, type "make
        check".  This will build the `info' docs for texidoclet itself in
        the "source" subdirectory.

## 8. Usage

Please note the following instructions relate purely to the old 0.5 version of GNU texidoclet, which is currently the only release

[Taken from the `README` file in the distribution]

    Usage:
    =====

    1.  TexiDoclet now works like any other doclet [Consult
        http://java.sun.com/j2se/javadoc/ for further information on
        Javadoc and the Javadoc API], it can be invoked with default
        options by merely supplying the path the doclet and the doclet
        invocation class (which is `gnu.texidoclet.Driver'):

    javadoc -docletpath TexiDoclet.jar -doclet gnu.texidoclet.Driver <filename> ...

    2.  It also accepts all the Standard Sun doclet options, in addition
        to some TexiDoclet-specific ones, which are listed if you invoke
        javadoc without any Java source files or packages.  Here are those
        options:

    -d <directory>            Destination directory for output files
    -tocbase         <base>   Prefix for all package-level texi files (default 'packages'
    -indexbase       <base>   Prefix for package index
    -allclassesbase  <base>   Prefix for all class list
    -treebase        <base>   Prefix for tree output
    -etagsname       <base>   Prefix for package etags
    -tocheader       <text>   Header for each texi file
    -tocfooter       <text>   Footer for each texi file
    -copyrightnotice <text>   Copyright information on each texi page
    -wordwrappos     <chars>  Number of columns at which to wrap
    -firstlineindent <chars>  Number of columns to indent
    -includeauthor            Include author information?
    -fulltreealignment <type> 'replace' or null
    -heritagealignment <type> 'replace' or null

        Most of these options are self-explanatory and all have
        `reasonable' defaults, and are in the process of being more fully
        documented.

    3.  To generate the `info' documentation, invoke `makeinfo' on the
        resultant `.texi' file.  See the documentation accompanying your
        texinfo installation for more details.  [Note you can use texinfo
        to also generate printed and HTML documentation from the `.texi'
        files, but note that there are more specialised doclets for that
        purpose].

## 7. Bugs

Please note the following instructions relate purely to the old 0.5 version of GNU texidoclet, which is currently the only release

[Taken from `BUGS` in the distribution]

    Known Bugs, or "features not yet implemented", in roughly the order
    they will be attacked. New versions of this software implementing all
    or part of the missing features can be expected soon.

    * No cross-links for parameter types, return types, and thrown exceptions.

    * No support for {@link}.

    * Not very configurable at the time.

    * Various small improvements on Info page layout pending.

    * Elisp scripts for context sensitive help are preliminary. (Can
      anyone help me out here? I am new to Lisp and would need some
      advice.)

    * Autoconf support for the Cygnus environment (simply untested at the
      moment).

## 8. History

[Taken from `NEWS` in the distribution]

    2002-01-24 -- CVS

    * now a GNU project (part of classpath)
    * all copyright changed to FSF.
    * distribution now based at http://savannah.gnu.org/projects/cp-tools/

    2001-04-02 -- 0.5

    * complete overhaul of distribution
    * distribution now based at SourceForge.
    * rewrote Makefile system to use GNU automake/autoconf
    * added a new Driver class to generate the .texi in one pass

    2000.04.02 -- 0.4.1

    * features full information - all documentation nodes are implemented
    * added "implements" information
    * added post-processing to include information about derived and
      implementing classes.
    * removed self-reference in heritage tree
    * improved node reference formatting ("(package) class" instead of
      "(package)class")
    * added switch to control inclusion of author information
    * added caption to index, all classes, and full tree node
    * added "abstract" keyword and class prototype to class node
    * added serialization node
    * added ability to split the full index into 27 parts (A-Z|_)
     (not configurable yet)

    2000.04.01 -- 0.3.3

    * index is now sorted case-insensitive
    * major revision of configuration file structure
    * added preliminary version of inherited fields and methods
    * took preparations for adding derivation information after generating
      the texi files.

    2000.04.01 -- 0.3.2

    * improved front page layout
    * added copyright messages as requested by Sun Microsystems Inc. so
      that the core API docs
    * can be distributed in converted format.
    * removed heritage chart from interfaces
    * added "extends" line to class node
    * added @author tag to all nodes

    2000.03.30 -- 0.3.1

    * added Interfaces, Exceptions and Errors to package node
    * fixed bug: bad layout when HTML paragraph ends with <br>
    * added @deprecated and @since info to all nodes
    * added support for multiple source paths

    2000.03.29 -- 0.2.1

    * fixed bug: class node only displayed first description line.
    * added @since tag for all nodes.
    * fixed bug: generated text displayed bogus texi tags.
    * corrected/finished full tree layout.
    * fixed bug: field prototype was missing.
    * <sup> is now translated to ^ (caret) for denoting powers.
    * Method listing in class node is now sorted.
    * added "see also" for classes

    2000.03.28 -- 0.1.2

    * Source code structure significantly improved.
    * added "all classes", full index, and full tree.
    * added preliminary emacs .el-script for context-sensitive help.

    2000.03.27 -- 0.1.1

    * Initial non-public pre-alpha release.

## 9. TODO

[Taken from `TODO` in distribution]

    * Check bug list.

    * Improve source code documentation and this page.

    * Check Speedbar compatibility.

    * Look for a way to add a link to the corresponding Java source code
      into all Info nodes.

    * Same for original HTML documentation (using browse-url)

    * Perhaps integrate XML/XSL support when it becomes part of the Java
      standard. Currently, the user would have had to download a package
      of some MB and install it, if an XML library would have been
      employed for TexiDoclet.

Return to GNU's home page.

Please send FSF & GNU inquiries & questions to gnu@gnu.org. There are also other ways to contact the FSF.

Please send comments on these web pages to webmasters@www.gnu.org, send other questions to gnu@gnu.org.

Copyright (C) 1999, 2005 Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

Updated: $Date: 2005/07/02 20:32:08 $ by $Author: mark $