texi2roff - Texinfo to nroff/troff translator

Copyright 1988, 1989, 1990  Beverly A. Erlebacher  (see copyright file)

Notes for Release 2
-------------------
Thanks to everyone who wrote to me reporting new commands, problems or
just sending friendly thank you notes!  Special thanks to Len Tower and
Bob Chassel at FSF for providing "inside info" on occasion, to David
MacKenzie for interesting and useful correspondence and to James Clark
(author of groff) for some extremely clever and knowledgable suggestions.

Thanks also to Norman Wilson, Henry Spencer, Ian Darwin and Geoff Collyer
for advising or commiserating with me about peculiarities of troff.

Special thanks to Rayan Zachariassen for conning me into writing
texi2roff in the first place.  By distributing and supporting this
program I've come to feel part of a very interesting global community.

New Features in Release 2.0
---------------------------
+  several dozen additional commands are supported, including the ones
   in the new elisp manual. 
+  tables of contents are generated. 
+  index entries are emitted and a script to generate indices is provided. 
+  file inclusion is supported (@include command)
+  appendices are "numbered" with letters. 
+  a font stack solves most nested font change problems
+  bug fixes, some prettier formatting, and somewhat tighter code.

New Features in Release 2.1
---------------------------
+  more new commands, and the redefinition of the @w command are supported.
+  the -I option is dropped, @iftex and @ifinfo are handled differently.
+  comments are handled differently (this is mostly a bugfix).
+  the large tablem?.h files are now tablem?.c files.  this should help people
   with weak compilers, e.g. microport 286.
+  due to popular request, the \input texinfo line is deleted.
+  a bug in the texi2index script is fixed.

Problems in Release 2
---------------------
Texinfo remains a moving target.  I've given up trying to track all the
subtleties and little elegances of formatting and am just trying to
provide you with manuals that are convenient to read.  The new @def
series of commands are particularly difficult to emulate - I've tried
to make them readable although the formatting is sometimes unaesthetic.

Please report any problems or "unrecognised command" messages to me. 
I usually don't know that a new manual with new commands is out there
unless someone tells me about it.

Font changes in section headers may not be handled properly when the headers
are printed in the table of contents.  

Going with the Flow - Onward into the Future - Self Help Guide
--------------------------------------------------------------
It's quite easy to add new commands yourself.  Find a command that is
syntactically similar to the new one and add the new command to the
tables in a similar way.  This assumes you can figure out what the new
command is supposed to be doing! texi2roff is table-driven, and the *.c
files containing executable code total less than 850 lines.  I added the
many new commands to release 2.0 without changing any of the .c files -
I only modified translate.c for the two newly supported command types
INDEX and INCLUDE. These commands were formerly discarded. If you add
new commands yourself, please report them to me anyway so other people
can benefit.

Usefulness
----------
I almost never print anything.  I find texi2roff useful for browsing
GNU documentation in a pipeline texi2roff | nroff | pager.  I like to
use the program 'less' for a pager since it allows string searches and
scrolls both backward and forward.  I'm mentioning this here because
this use seems not to occur to people - some are surprised and pleased
when I tell them about it.

There will soon be a standalone info file reader available from FSF.
In the interim texi2roff can be used this way.

Portability
-----------
Texi2roff was tested on a variety of machines and environments.  It
even runs under ms-dos!  There is a -DBSD directive in the program
which only controls which string header to #include and which of
strchr() or index() is used.

Please report any portability (and other) problems you encounter.

I'd like to thank the beta testers of release 1.0 and the new ones of
release 2.0: Jim Ingram, Marty, Richard Murphey, Scott Garfinkle and
especially Bob Willcox.  Had this small group of the many I sent source
to not responded, I would have had to conclude that texi2roff was
either incomprehensible or perfect.

Thanks also to those people who reported bugs and new commands for 
release 2.1: 

Texinfo, LaTeX, TeX, troff, texi2roff...
----------------------------------------
Texi2roff translates Texinfo documents, *NOT* TeX or LaTeX documents.
Not all GNU documentation uses Texinfo, although most of the recent
material does.  Texinfo commands all start with @ while LaTeX and TeX
commands start with \.  If a document has a line containing:
	\input texinfo.tex
near the top, it is a texinfo document.  Several people have asked me
whether programs exist to convert TeX and LaTeX documents to troff. 
I don't know of any.  If I were to write one, I think I would first
write a customised macro package for troff that a texi2roff-like
program would translate to.  If someone would like to collaborate on
such a project, please contact me.

Beverly Erlebacher      ...uunet!utai!erlebach  erlebach@cs.toronto.edu
8 Roblocke Ave.
Toronto, Ontario, Canada  M6G 3R7

