[OS X TeX] MacTex 2008 documentation (Again !?!?!?!)

[Jean-Christophe Helary]

After all I learned over the course of the weekend, I was thinking  
that the best way to contribute back to the "community" was to do two  
things:

1) propose modifications to the "READ ME FIRST.pdf" file that is put  
inside the /Applications/TeX/ folder

2) propose a template for multilingual use that works out of the box  
(to a certain extend) to the Texshop developers so that it can be  
referenced in the above document.

About 1), I could not find the source of the document. Is it hidden  
somewhere in the distribution architecture ?




Now, for those who are interested in knowing what exactly happened,  
here are the minutes...




Basically what happened is the following: I had an old fink+macport 
+native mix of tex related packages that I wanted to put to use  
sometime.

When I decided to typeset that French book about kanbun I had figured  
out that only Unicode could help me. So I googled a little bit and  
found (again) about XeteX.

After checking the XeteX page, I found that its most recent version  
was available in MacTex. But since I already had all the stuff  
installed I was reluctant to download 2gb of data that I would only  
use to typeset once a 100 pages book. So I tried my old Texshop with  
my old XeteX, saving the file in UTF-8 etc but things did not work  
well. I tried and tried again but could not get accents (or Japanese)  
to display properly. My first idea was that my system was broken  
(after all I _was_ using Unicode and XeteX and the default templates)...

So I decided to purge everything: I removed the whole /opt/ and /sw/  
trees, the old native apps (Texshop etc) and proceeded to download  
MacTex.

Installation worked flawlessly.

Then I read the READ ME FIRST.pdf file, proceeded to set the new  
version of Texshop, opened the default template and... Shock and  
horror ! It still did not work.


That is pretty much what led me to the list and started this very  
interesting thread.


Now, _IF_ the READ ME FIRST.pdf file had contained the 2~3 lines of  
preamble that would have allowed me to proceed with French (or at  
least give me hints that non English languages were "special", along  
with a pointer) all this would not have happened... Believe me.


I put myself on the seat of the user who knows the software is  
supposed to produce the expected result (because it is advertised as  
such) but can't find the damn button to make that work. And also can't  
find the document in the box that says where the damn button is.

You all have been very helpful and I am truly grateful for all the  
mails that were exchanged. But the thing is that, just like feeding  
someone is not like teaching that person how to grow potatoes, sending  
recipes in a mail will most likely not contribute to the user's  
independence (just like sending arbitrary links to documents - 
displayed in super tiny fonts or not- in the TeX universe).

While saying: "since you have MacTex 2008, then look into the (MacTex  
user meta manual).pdf, page n, all the basic settings are there" does.

It takes one line, one mail and that part of the thread is over.

And the documentation should be right there, in the box.


It does occur to me that a lot of modern documents related to (La)TeX  
are published in English, with the English reader in mind. I found a  
few and they really are good. But the issue with them is that when  
they mention "fonts" it usually comes with the warning that the user  
should really not be touching them because TeX is a specialist and  
knows about all that, and when they mention encodings or languages it  
is mostly by mentioning that the packages support multiple encodings  
and/or multiple languages. Wow.

No wonder that translation of such documents, if they exist, mention  
font modifications and encoding issues somewhere in the middle of the  
book, exactly where the English text mentions them (like on page 346  
of a book somebody mentioned in the thread...) When such information  
is simply vital to the non English user and should be in a prominent  
location so that the user is simply able to start typing !!!


Jean-Christophe Helary


ps: "That's what Open Source/Free Software is about so deal with it"  
is not an argument. I am the owner of a (close to) 1000 members  
specialized software user support list, I authored 2 versions of the  
manual (about 650ko of HTML data for the latest) and contributed to 2  
others, I contributed French localizations and Japanese localization  
coordination, along with the Mac packaging etc, and I find it a gross  
misconstruction to suggest that volunteer work produces lower grade  
user experiences where most of my experience as a software user says  
the _exact_ opposite.