[OS X TeX] Building new formats (MacTeX)

[Bruno Voisin]

To Rowland:

About documentation
===================

This is the world of open-source software. All the documentation that  
exists is the one that we point out to you. In open-source software,  
it can be either:

- Well-written pedagogical manuals (rare).

- Badly-written, or non-pedagogical, manuals (often).

- ASCII ReadMe files, or man pages (too often).

- Help files (too often).

- Documented source code (in perl scripts, for example, or TeX macro  
files).

- Wiki pages (more and more often, sometimes there's not even any  
other documentation).

- Mailing lists.

Originally none of us had more documentation that you do. The way we  
learnt is by reading this documentation, experimenting, asking and  
listening to this list, reading tips somewhere on web pages,  
experimenting again, and so forth. This is how most open-source  
software works.

If (as I think) you are not happy with that way of working, and you  
would like more formatted documentation, or a higher level of  
support, then I think you should really consider commercial software.  
Not that you would be sure of getting that documentation or support:  
in more and more commercial software that I see, not even a printed  
manual is provided with the software.

I, too, would like to see better documentation, and printed stand- 
alone manuals, like the Textures or OzTeX User Guide. Alas, that  
seems a thing of the past. I don't like to have to read source code *  
(see note below), or to know that I need an internet connection in  
order to use a software (so that I can ask questions to a mailing  
list). Alas, that's the world we live in.

Many people from this list have shown a lot of dedication in  
answering your questions. I don't think you realize how exhausting it  
is, spending a lot of time attempting to provide answers, and knowing  
that afterwards requests for even more details will come. Really,  
there is no hidden source of information that we have access to, and  
that you're not aware of. The way we, or at least I, proceeded is by  
reading some documentation, and messages from this list, which  
proposed a solution to a problem; and then trying it, and usually  
breaking everything in my TeX setup; and then trying again, and  
again, and again, until it all started to make sense and I could feel  
I had started to understand. Probably not optimal, but that's the way  
open-source software works: by trial-and-error.

About installers
================

The mother of all antisocial installers is probably Adobe software.

In case you've installed the free Adobe Reader, you possibly haven't  
noticed it, but on first launch Adobe Reader has installed a PDF  
Browser plugin AdobePDFViewer.plugin inside /Library/Internet Plug- 
ins. This plugin is activated by default, and use of the Reader  
Preferences to disactivate it didn't work until the most recent  
versions (every time you read a new document in Reader, the plugin  
was re-activated).

Even worse, on first launch Reader installs frameworks inside Safari  
itself -- yes, it does modify the Safari application. Without asking  
you, or even telling you.

The non-free Adobe Acrobat is even worse; not install does it do the  
above, but in addition it also modifies the behaviour of Microsoft  
Office applications and installs a new Adobe PDF 7.0 printer.

As regards Office, Acrobat installs a PDFMakerLib inside "/ 
Applications/Microsoft Office 2004" and macros for Word, Excel and  
PowerPoint inside "/Applications/Microsoft Office 2004/Office/ 
Startup". These add a new toolbar with two PDFMaker buttons to Word,  
Excel and PowerPoint, eating even more screen estate.

As regards the Adobe PDF 7.0 printer, I've given up on trying to  
trace down the various pieces it corresponds to inside /Library/ 
Printers, so that I could erase all of them.

Moreover, all these files are Self-Healing in Adobe parlance, which  
means they are recreated automatically when Adobe applications  
detects they are missing.

Just a few examples of what truly bad installers are...

Bruno Voisin

* Absolutely OT: I recently received from a colleague a CD of  
experimental data (for comparison with my proposed theory). Most of  
them were ASCII files containing single-column lists of numbers, with  
no documentation at all. After some search, I finally realized the  
explanation could only be found by reading the -- uncommented --  
MATLAB scripts used to manipulate the experimental data. From these  
scripts, and the names of the variables in them, it finally came out  
that: the first 10 lines of each file were experimental parameters;  
the next 512 lines, values of the measured quantity at 512 different  
values of y, for a given value of x; the next 512 values, the same at  
the next value of x; and so forth. O the fun of reading undocumented  
source code!
------------------------- 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/