doc suggestion, was: [XeTeX] beginners trouble

[Martin Henning]

Hey Will,

On Nov 13, 2005, at 9:01 AM, Will Robertson wrote:

> Okay, sorry to hear this. As a bit of a non-beginner these days, I  
> have a hard time remembering what it was like when I didn't  
> understand anything :)

Not at all sorry, your documentation is great, verbosity is also very  
muh apreciated! Just... i will try to point out the beginners  
problem ;))

> Now you have solved your problem, can you give me any tips on how  
> the fontspec documentation could be made clearer? I tried to make  
> it as straightforward as I could, with lots of examples, but giving  
> it a re-read now I suppose it's all rather verbose.

I suppose a few lines about what is really _just_ nesecary to use the  
package would be enough. You state it every once in a while, e.g. in  
the beginning, but i guess as beginner you are trying to get aa broad  
picture, as to what the hell the whole thing is doing. Unfortunately  
the XeTeX documentation is mor ethan weak, so even though you  
slightly understood LaTeX system itself, you suddenly don't know  
anything anymore, since u read things like "use euler for math", "use  
fontspec", "use xunicode" etc :) So for my part, i still don't know  
what's the big problem with unicode and xetex and the existing  
commands and whih will be working and which (and why) won't...

For fontspec maybe a suggestion: I always try to find examply files!  
I got many XeTeX example files, but they contain more or less a show- 
off of advanced and fancy stuff! What the beginner really needs would  
be something like a verbosely commented very basic example file à la:

*first you need this package because of...
*secondly, because XeTeX internally doesn't know what fonts to use,  
you should choose some
	-either whole font family
	-or vor advanced users with more sophisticated rules, see doc page xyz
*--- that's all it takes --
	- there are advanced features to achieve things like
		-this, see doc page zyx
		-and that, see doc page bla

Got my point? Beginners need a broad picture, to understand what's  
going on :) Same documentation example could apply to XeTeX itself...  
the broad picture is missing. You think of it as one hell of  
configuration thing after you read about UCS package and spent nights  
and days with inputenc and other stuff! :) In the end it's not even  
one line that is needed to work out. Like fontspec - the actual  
working solution apart from advanced features turns out to be so easy  
and understandable, that i supposed it could have kept more users  
from giving up in the middle of dicovering unicode TeXing :))

> I would be very grateful to receive your, and anyone else's,  
> feedback on this matter.

I'm very grateful for you package, and i like the documentation, now  
that i fairely understood what is going on... the advanced features  
will take me some more time.

As for XeTeX i will still have to get the broad picture :)

Thanks all,

Martin