[OS X TeX] Building new formats (MacTeX)

Tue Sep 19 12:32:23 EDT 2006

Le 18 sept. 06 à 23:28, Rowland McDonnell a écrit :

> [...]
>
> I'm looking for straightforward explanations with examples.
>
> Hints and implications don't help.

Straightforward explanations with examples, of the kind you're  
looking for, simply don't exist. In open-source software, developers  
generally don't provide that form of documentation. Probably because  
they don't have the time (it would have to be taken away from time  
spent on coding and making the software better), or because they  
don't have the skills, or because a developer doesn't necessarily  
have enough perspective on a product he's creating himself/herself to  
provide the best documentation. All that is generally provided is  
bare-bones documentation, FAQs, online help files, man pages,  
documented source code and so forth.

Often extensive, pedagogical, straightforward documentation  
accompanied by examples is provided later by enthusiastic users who,  
after months or years of use of the software, decide to write this  
documentation. For example, ConTeXt is sometimes criticized for not  
having enough documentation; because of this, two enthusiastic users,  
Steve Peter and Adam Lindsay, are working on a book on it, presenting  
things from the user's perspective. GraphicConverter, too, for  
example (though not open-source), is shipped with a bare-bones manual  
but offers the opportunity to purchase an alternative manual written  
by an enthusiastic user. Ditto for OpenOffice.org (for which you can  
also get paid support by purchasing StarOffice from Sun), Firefox and  
Thunderbird (for which you can also get paid support from the Mozilla  
foundation), and so forth.

Similarly, remember: Knuth's TeXbook (for plain TeX) and Lamport's  
"LaTeX: A Document Preparation System" (for LaTeX) were often  
perceived as difficult to use for beginners, and this led to the  
numerous books like Seroul's & Levy's book for plain TeX and Kopka's  
& Daly's book for LaTeX.

Another way of getting full documentation for open-source software is  
when writers, specialized in software documentation, write manuals  
published or commissioned by commercial publishers. Think of Pogue's  
Missing Manual series, for example, and of all the O'Reilly books.

For commercial software the method is similar: either a software  
company has a team specialized in doc writing, or it hires an  
external consultant to do the job. Think of the Textures User Guide,  
for example, written by Mark Metzler who, if I'm not mistaken, also  
took part in writing the original Inside Macintosh series of books,  
documenting the early versions of Mac OS (on 128 K and 512 K Macs).

For teTeX (now defunct) and TeXLive (the now standard multi-platform  
TeX distribution, from TUG), no such documentation exists. I don't  
think anybody on this list would have the time to provide it for you.  
All that you'll get is, I think, hints and implications; until now  
all people on this list have been happy with them. The amount of  
detail and step-by-step instructions you ask for, practically to the  
keystroke, is unprecedented.

To get the kind of documentation you're looking for, I see only three  
solutions:

- If you have enough free time, a taste for experimentation and the  
skill for pedagogical writing, then be that user who studies the  
software and ends up writing the missing documentation for others.

- Hire a TeX consultant.

- Switch to a commercial TeX distribution.

Two more things:

- In contradistinction to your opinion that open-source developers  
like their users to be left in the wild as to what their software  
really does, an email message between Gerben Wierda and Hans Hagen  
(the developer of ConTeXt) at the time the documentation for the  
MacTeX package was prepared (on the private MacTeX list). I don't  
think that either Gerben or Hans will mind my reproducing the message  
here, given the purpose:

> Le 23 sept. 05 à 09:26, Hans Hagen a écrit :
>
>> Gerben Wierda wrote:
>>
>>> One could add "quality of documentation" and "amount of  
>>> documentation" as rows.
>>>
>>> There are a few things with ConTeXt documentation that make it  
>>> very difficult to use in my experience. The most important are
>>> - that it is sometimes out of date
>>> - that there are not enough real live code examples, it is  
>>> assumed the reader immediately understands a grammatical  
>>> description of a command (that is "programmer thinking" not "user  
>>> thinking")
>>> - that stuff is missing.
>>
>> There will be a book about context written by Steve Peter and Adam  
>> Lindsay (they're working on it). Concerning the context  
>> documentation and maintainance ... one problem is that people ask  
>> for features faster than i can write; actually this is a rather  
>> general problem since getting the latex companion up to date also  
>> took years of writing, testing etc. I still have to find the right  
>> method of getting things in sync (well, look at operating systems,  
>> they lack documentation and one always has to google ...); maybe a  
>> more database like approach suits better, anyhow, my continiuous  
>> struggle ...
>> another problem is that - negative side effect of mailing lists  
>> and internet - that tex users no longer write many articles (as in  
>> the early days of tex); many introductionary things originate from  
>> the past;
>> one thing that i will do as soon as i have time (and the right  
>> equipment installed) is to put all manuals and other stuff that i  
>> have (basically the manual source code is nice example code) under  
>> a svn repository, but  i need to set that up here first as part of  
>> our new office infra structure, so ... i hope that in the end  
>> documentation sorts out
>> Hans

- You've written me off-list about my font installation tutorial.  
Merely writing the tutorial, with all the included knowledge already  
gained after years of experimentation with TeX, in its various Mac  
incarnations (Textures, OzTeX, DirectTeX, CMacTeX, TeXShop/gwTeX),  
took most of the nights in a whole week. The tutorial is notoriously  
not up-to-date. I would have loved to keep it up-to-date; but I  
simply can't find the time. Similarly, answering, in the manner you'd  
like, the questions contained in your various messages would take at  
least about the same time as writing the tutorial. I don't know  
whether anybody here can afford it; I can't.

Bruno Voisin------------------------- Info --------------------------
Mac-TeX Website: http://www.esm.psu.edu/mac-tex/
          & FAQ: http://latex.yauh.de/faq/
TeX FAQ: http://www.tex.ac.uk/faq
List Archive: http://tug.org/pipermail/macostex-archives/