XeTeX doc - was: [XeTeX] Newbie ...

[Robert Spence]

Dear Martin,

On 05 Apr 2006, at 08:20 , Martin Henning wrote:

> what about starting a small wiki just for documentation purposes?  
> it might start out only as some kind of unordered FAQ list, which  
> might evolve into and ordered and later even properly outlined  
> dokumentation/howto/... what do you think?

I second the motion!

> upcoming important questions and their solutions might actually get  
> compiled into the XDE (XetexDocumentationEffort :)) very quickly  
> and also edited as XeTeX itself developes. Starting a new thread we  
> might discuss a documentation outline as a starting point.

In writing documentation, we'd probably need to consider the needs of  
different sets of users, e.g.
a) people having problems with the differences between XeTeX and  
LaTeX2e, versus people who are migrating directly to a unicode  
version of TeX from outside the TeX world; also:
b) people wanting to re-process and maybe extend existing documents  
(whether written for TeX or for some other system) versus people only  
interested in creating new documents.

So maybe a "HOW-TO" approach might be best initially.

If we ever get around to doing full documentation, it might be worth  
taking cultural differences into account: should we aim for a German- 
style systematic introduction (which could get very wordy, but would  
certainly give a _complete_ overview), or a more personal, voyage-of- 
discovery approach (as adopted, for example, by Knuth in the  
TeXbook)?  Anglo-Saxons love (and are good at) the second approach,  
but I've often encountered situations where it has failed dismally  
with continental European students (more so with German students, who  
need the systematic overview; less often with French students, for  
whom a dialectical approach to a problem is apparently more familiar  
from their philosophy classes at high school).

If there was time, we could write a special version of the  
documentation that was aimed at UNIX sysadmins.  The most appropriate  
way of doing this would be to write it in Japanese and have it badly  
machine-translated into English.  (I'm not kidding.  This was the  
result of an internal study commissioned by a big multinational IT  
corporation that takes documentation seriously.  All the efforts of  
the text linguists involved, tracking down what was wrong with the  
existing documentation and how it could be improved, only worked for  
the "man on the street".  The sysadmins could only make sense of the  
existing badly machine-translated documentation, without any  
improvements.)

If the "official" documentation is eventually going to be in  
hypertext form, it might be worth considering the possibility of  
implementing the kind of "intelligent" technology that notes readers'  
link-clicking habits and tries to deduce something about their level  
of knowledge and their interests; but maybe not. (Think of how stupid  
Amazon's individualized recommendations to customers can be at times.)

Here's a personal summary of my first encounter with XeTeX:

Since deciding to take the plunge and switch from LaTeX2e, I've found  
my normal levels of TeXing chaos have increased somewhat, with the  
result that it's often difficult to retrace the steps I took. So I'm  
not sure I'd be able to distil much from my own experiences that  
would be useful to others.  But some of the issues that have come up  
for me so far have been:

1) Trying (as a newcomer searching the XeTeX list archives) to  
distinguish between
a) minor bugs that got sorted out long ago, and
b) feature requests from long ago that are still unimplemented  
because the attempt to implement them would impact on central design  
parameters of the XeTeX project.

2) Trying to cope with a mixture of more TeX-like and more LaTeX-like  
syntax (the "vertical" dimension within XeTeX) and, at the same time,  
the "horizontal" differences between LaTeX2e and XeTeX-plus-essential- 
macro-packages; here the learning curve was steeper than I expected.

3) Trying to assess the probable lifespan of many of my current  
"emergency" workarounds.  Many of these "emergencies" appear slightly  
less vexing in view of the posting by Jonathan Kew on 28 March,  
concerning the xdv2pdf driver versus the dvipdfm(x) driver and the  
implementation of the new \XeTeXuseglyphmetrics command in the coming  
version 0.991 of XeTeX.

4) Trying to get an overview of what kinds of XeTeX macro-packages  
people are working on as a replacement for, or as an extension of,  
existing LaTeX macro-packages, i.e. what needs to be done, and who's  
already got it half done.

Apart from these issues, I'm extremely happy with XeTeX.  It seems  
ideal for people who
a) can't imagine anything worse than having to do WYSIWYG word- 
processing, and
b) can't imagine anything better than being able to work on some kind  
of UN*X hiding behind a stylishly-designed GUI.
But not everyone coming to XeTeX will be on those two trajectories.

The only unsolvable problem associated with going XeTeX is what the  
Germans call "the torment of the choice" ---all those incredible  
fonts, each with its advantages and disadvantages...

So... who's going to install the Wiki software? And where?

-- Rob Spence