This package, Iraftex, provides tools for translating IRAF online
documentation (*.hlp files) into LaTeX and HTML.

The current version is a prototype. Constructive feedback is highly
appreciated.

Contents of this file:
- Introduction
- Installation
- Use
- The future and some wild ideas
- Supported subset of IRAF *.hlp files
- License
- Contact information


Introduction
~~~~~~~~~~~~
The IRAF online documentation is written in a language supported by the
lroff formatter inside IRAF. This language is similar to nroff/troff
in the Unix system. Being designed for text output the semantics of the
language is somewhat tied to a current indent counted as the number of
space characters. But the language also have a simple block structure
that matches similar structures in LaTeX and HTML quite nicely.

The aim of this project is to translate the IRAF online documentation into
(sorry) more modern formats like LaTeX and HTML. The translation uses
the block structured part of the language and ignores for most parts the
`number of spaces in the current indent' bias of the language. Most of
the IRAF online documentation can be translated using this approach with
good results.

The motivation for doing this project is to obtain nice looking prints of
the IRAF online documentation. LaTeX was chosen for its high typographic
quality and because the author is already familiar with it. Support for
HTML was added from the beginning of the project because it was easy to
do and could be useful for others. Part of the motivation for doing this
project is that it may be useful to the IRAF user community.

Much of the inspiration for this translation comes from the IRAF V2.11
Release Notes on the IRAF web site (http://iraf.noao.edu).


Installation
~~~~~~~~~~~~
(1) Edit `Makefile' and set `prefix' and/or `bindir' and `libdir'
    to appropiate values.
    
    Set `awk' to the awk program you want to use.
    GNU awk is highly recommended.
    
    Note on mkdir: If your `mkdir' command does not support the `-p'
    option then remove it from the `mkdir' definition in the
    `Makefile'. You may have to create some of the directories
    by hand.

    Note to Digital UNIX users: If you are using Digital Unix the
    author recommends that you get `bison' and `gawk' from your
    nearest GNU archive and install these first. The awk programs
    supplied with Digital UNIX system is not very good at handling
    regular expressions.

(2) Type `make install' to install the package.
    It should now be ready to use.
    Please make sure the installed commands are in your PATH.


Use
~~~
To translate IRAF *.hlp files into LaTeX, type:

	hlp2latex <file_1> ... <file_n>

The output is stored in `<file_i>.tex' for each `<file_i>' supplied
on the command line. The resulting file can be included in a LaTeX2e
document. Please refer to `try.tex' for an example for such a document.
A recent version of LaTeX2e and a fairly complete installation of
TeX/LaTeX is required.
The current translation uses:
- The `alltt' package (part of standard LaTeX2e)
- The `fancyhdr' package for headers (contrib)
The author recommends using the `T1' encoding as it provides the best
support for double quotes.

To translate IRAF *.hlp files into HTML, type:

	hlp2html <file_1> ... <file_n>

The output is stored in `<file_i>.html' for each `<file_i>' supplied on the
command line. The resulting HTML file is can be directly read by a suitable
HTML browser. The author has only tested the output with netscape 4.0x.

If a directory is specified to any of the above two commands all `*.hlp'
files in this directory will be translated.

The future and some wild ideas
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The translation has revealed a number of (minor) errors in the IRAF
help files. It could be nice to fix them. At the same time, one could
convert them to use the block structured subset of the IRAF help file
format supported by this package. Also, a standard for the typographic
conventions in the online documentation could be useful, e.g. when to use
bold and italic and how to make displays. Of cause, one should be careful
about requesting such changes in a system with such a long history.

Some sort of support for hyperlinks would be nice, as suggested by Mike
Fitzpatrick when he saw an early version of this package.  There are two
ways to do it. Either add explicit markup to the lroff language. This
will require extensive editing of the online documentation. Or find some
way of doing it automaticly.  One problem in this case is that some of
the parameter names are commonly used words like `input', `output' and
`image'.

Support for hyperlinks in PDF files (Adobe's Portable Document Format
which are read using the Adobe Acrobat reader) is also one way to go as
it will combine hyperlinks with high typographic quality.

The translator is quite slow due to the use of awk. If there is sufficient
interest the author may rewrite it in C. This reimplementation may also
support a larger subset of the lroff language, including hyperlinks to
parameter names and a fix for the problem with `mkpkg.hlp' mentioned
below.


Supported subset of IRAF *.hlp files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The supported blocks are:

	.NF
	  ...
	.FI

	.LS <text>
	  ...
	.LE

	.LS
	  ...
	.LE

	.IN +n
	  ...
	.IN -n

Supported directives (other than the blocks):

	.HELP <page> <date> "title"
	
	.HELPSYS <page> <date> "title"

	.SH
	<text>

	.IH
	<text>

	.NH [<skip>] <n>
	<text>

	.CE
	<text>

	.SP

	.BR

The current implementation has the following restrictions:
- The RJ directive is not supported yet.
- Font changes cannot span multiple lines.
- A few help files fails badly, `mkpkg.hlp' is one of them. It is
  due to its use of negative indents
	IN -n
	...
	IN +n
  which is not supported by the translator.
- Line numbers in error messages may not be correct due to the translators
  two-pass implementation.

Implementation notes:
- Both LaTeX and HTML uses description lists with explicit
  start and end markers. This is implemented by placing a
  LE followed by a LS in the same description list and
  starting/ending the description list otherwise. This matches
  the use of LS/LE blocks used in many/most help files.
- LS/LE block without a text argument to LS is considered to be
  identical to an IN block.
- Indented text lines has to be handled specially as many help
  pages use indented text as a shorthand for NF/FI blocks.
  To complicate things further some help pages indents the first
  line in a section and putting such a line inside a NF/FI block
  is going to look quite bad and hence not done.

License
~~~~~~~
(This license applies to all files in the distribution even though
 not all files have a copyright notice.)

Copyright (c) 1998-1999 Klaus Elmquist Nielsen

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

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, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Contact information
~~~~~~~~~~~~~~~~~~~
klaus.elmquist@get2net.dk

Klaus Elmquist Nielsen
(Somewhere in Copenhagen, Denmark)

Last updated: 19990518