🚀 go-pugleaf

Recently I went through the experience of figuring out Texinfo and
then backtracking away from it because I felt it was not right for my
problem.  I summarise my opinions on Texinfo below ... they may help
others make similar choices and they may help motivate improvements in
Texinfo.

The intended area of application was writing the manual for a C
library for statistical computation.  Writing library manuals is quite
dreary with LaTeX, and Texinfo does have excellent hooks for easily
documenting functions, maintaining function indexes, etc.  I like
using info online too, and the promise of getting a online queryable
manual "for free" felt quite good.  So I grabbed the manual and
uploaded it into my head one night.

Please be warned -- my knowledge of Texinfo is not great.  I have
written two chapters of my manual using it, I have read the manual
once, and I've asked a few questions on the net.  I'm not an authority
on it.  Some of what follows could be grossly off track because of my
poor knowledge.

Summary Pros
------------

0. Texinfo is quite different in the overall look-and-feel from TeX.
It's a tribute to TeX that one could produce such a system by writing
a style file on top of it.

1. All in all, I think it's easier to use than either TeX or LaTeX (at
the price of more restrictions).  The @ notation frees up a lot of
special characters (I hate $\backslash$ e.g.).  It's a better program
in terms of cleanness and orthogonality than TeX, IMHO.  If you are a
Unix mind then you will enjoy Texinfo.  I, for one, thrive on awk and
C, and have repeatedly felt frustrated at Knuth's design of language
-- he is one of my shortlist of Great Gods but he sure has a terrible
sense of taste in programming language design.  (You guessed it.. I
have a strange love-hate relationship with TeX).

2. There is a happy incest between Emacs and Texinfo.  The Texinfo
mode in Emacs makes writing Texinfo documents very convenient.

3. You get online queryable files as a byproduct of the manual writing.

4. The indexing concepts are excellent.  

5. Texinfo is focussed towards writing software manuals, and it shows.
E.g. there is a primitive named @deftypefn for documenting a function
for a typed language.  There are hooks for documenting OO classes.
Etc.

Summary Cons
------------

0. Because it's "so different from TeX" you lose by not being
able to use masses of PD stuff for TeX -- style files, hooks for
putting pictures in, etc.

1. It won't work with Bibtex, and there is no alternative replacement.

2. You do get info files for online use, but it's certainly not "for
free".  You have to pay quite some effort to get a good info file out
of a document.  (This is not so much a "con" as a warning.  Don't go 
into Texinfo thinking you will get a info file for free).

3. Mixing mathematics and Texinfo is, bluntly, a nightmare.  The
TeX sentence

The most beautiful equation in all mathematics is $e^{i\pi} + 1 = 0$

translates into

The most beautiful equation in all mathematics is
@ifinfo
exp(i pi) + 1 = 0
@end ifinfo
@iftex
@tex
$e^{i\pi} + 1 = 0$
@end tex
@end iftex

which is a ghastly loss in productivity for me, since every alternate
paragraph I write uses $mathematics$.  Some of it is unavoidable
(since you want both a plaintext info file) but surely there was
a way to get the same functionality at the cost of fewer keystrokes?

4. There is zero programmability.

I paused in shocked silence when this dawned on me.  This is Unix, and
every other program in /bin contains a small programming language.
[nt]roff are certainly programmable.  TeX is programmable.  rms is one
of my Great Gods.  How could Texinfo have zero programmability??

There is a conditional compilation facility, and that is all.  There
is not even simple macro expansion like cpp.

IMHO allowing no programmability is a very bad idea in system design.
It's the kind of thing we usually associate with the cretinous
software from Mediocresoft.  Programmability of tools gives the user
more freedom, and enables uses of the tool which the designer never
thought of (/usr/games/fortune calls this attribute a sign of a good
software tool). 

I routinely use \def macro expansions in my writing, and while I tried
a bit to use Emacs abbreviations to replace the lack of a macro
expansion facility, it was clearly cumbersome.  I also got a whiff of
that hunted feeling I normally get when I'm around "cretinous software
from Mediocresoft", or the thought "What when I want to do something
which the designers of this program did not put in directly????".  I
lose sleep at night under such circumstances.

So, after much agonising, I decided to go back to TeX (or LaTeX)
to write my manual.  Texinfo is great, I might use it in the future
for writing other sorts of manuals, but for my job right now it's
not the tool of choice.  I hope it's enhanced in ways which address my
complaints, so I can use it in the future.

Just MHO, of course... your mileage may vary.

        -ans.
-- 

Ajay Shah, (213)749-8133, ajayshah@usc.edu