README file for tex-refs
========================

$Id: README,v 1.16 2003/04/12 16:11:59 mw Exp $

This file contains very brief instructions on how to build the
various output formats (in case you want to do this yourself for
some reason or just want to see how we handle all the 'magic').


Where to find
-------------

You'll find the latest version of 'tex-refs' at
http://www.miwie.org/tex-refs/


Requirements
------------

- DocBook XML V4.2
  Your Linux distribution should provide an up-to-date package for this.

- DocBook XSL Stylesheets (V1.60.1 as of this writing)
  Your Linux distribution should provide a package for this.
  If you only find an older version, try it or get the tarball
  from http://sourceforge.net/projects/docbook/, install it
  at some place and adjust some pathnames in Makefile.cfg.in

- XSLT processor
  At least xsltproc from libxslt/libxml2, and Saxon should work.
  xsltproc (libxml2-2.5.6, libxslt-1.0.29) is still generating 
  an incorrect index.

- make
  Should already be installed on your system

- openjade
  If you want to validate the XML file you'll need this

- DocBook DSSSL Stylesheets
  If you want to generate RTF output you'll need this

- htmldoc
  If you want to generate PDF output you'll need this


Installation
------------

- Choose a directory where to unpack the tarball and unpack it
  with 'tar xzf tex-refs-0.X.Y.tar.gz' (you already did
  this, otherwise you wouldn't be able to read this file)

- Copy Makefile.cfg.in to Makefile.cfg

- Edit Makefile.cfg
  This file is fairly well documented. In general you'll need
  to find out some pathnames (e.g. using 'locate') and edit
  the appropriate places

- Run 'make config'
  This modifies some pathnames in some files (XML, XSL) to reflect
  site specific pathnames


Usage
-----

- Run 'make targets'
  This lists the most important targets of the Makefile

- Run 'make'
  This will generate all currently supported output files

- Read over 'Makefile' if you want to know more details
  

Contact
-------

Contact the authors if you have any suggestions, enhancements,
corrections, etc. Your contribution is very welcome.

We have setup a mailinglist for people interested in contributing 
to this project. Subscribe by sending email to 
mailto:tex-refs-request@mlists.in-berlin.de containing the word 
subscribe in the subject or body of the email. 

You can find the archives of this mailinglist here:
https://mlists.in-berlin.de/pipermail/tex-refs/

-- 
Peter Karp         <tex-refs@karpfenteich.net>
Michael Wiedmann   <mw@miwie.in-berlin.de>
