[OS X TeX] Building new formats (MacTeX)
bvoisin at mac.com
Tue Sep 19 18:32:23 CEST 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
- 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
>>> - 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
- 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/
More information about the macostex-archives