[OS X TeX] Building new formats (MacTeX)

[Rowland McDonnell]

> To Rowland:

To Bruno: this message of yours that I'm replying to should have been
sent directly to me, since I think it's a bit off-topic for the mailing
list.  However, since you've presented an impromtu and unasked-for
lecture with factual errors in it that are relevant to TeX and whatnot,
I think it makes some sort of sense to send a reply to the mailing list
to correct your mistakes.

This is *NOT* meant as any kind of personal *anything* - I'm just trying
to deal with the `important issues'.

> About documentation
> ===================
> 
> This is the world of open-source software.

Not exclusively, it's not.  This is the world of TeX: I've been using
it since the early 1980s, well before that term was in common use. 
I've been using LaTeX since 1989 (or maybe '88).

Do not try to teach your grandpa how to suck eggs.  It just results in
embarrassment for the `teacher'.

Open-source does not mean `not for sale': it's not the same as `free
gratis for nothing'.  Bear that in mind.  And not all (La)TeX stuff is
open-source or `free of charge'.

It strikes me that rather than writing this supercilious lecture to me,
you would have been better off spending your time writing some useful
instructive documentation for TeX on MacOS X.  Why not?  You've got the
time, you've got the knowledge, you've got the ability.  Why waste your
time sneering at me in public (you're doing it to put me down in an
attempt to change my behaviour - /not/ a good use of the mailing list,
and doomed to cause nothing but irritation in any case) when you could
be spending your time constructively, in a way that could benefit future
users?

What about me, I hear you cry.  Well: do you have copy of the LaTeX
Companion?  Can you read indexes?  See what you can find under
`McDonnell'.

As I say, `grandpa', `eggs', all that stuff.

What you need to bear in mind is the fact that this is open-source
software has nothing whatever to do with issues to do with
documentation.  In recent years, even the fully commercial closed-source
software market has moved to `not supplying documentation'.  Back in the
late 80s/early 90s, I was used to learning about software via excellent
interactive multimedia tutorials.  These days, expensive software such
as the MacOS is supplied without any real documentation at all - Mac
Help is not what I'd call documentation (what I've had cause to look at
recently has mostly been advertising).

Take OmniGraffle, for example: that one was so badly documented that I
couldn't understand what it's for, let alone have a clue how I might use
it.

What's going on is a general malaise in the computing world: everyone
has their own excuse, but the upshot is that virtually no-one bothers
documenting their software.  The users suffer because they don't get to
learn how to use the software due to this absence of documentation.

> All the documentation that  
> exists is the one that we point out to you. 

Only one person has given me proper information about available
documentation, and I didn't get the feeling that he was providing
*definitive* information.  So how can I be sure that what you tell me is
true?  I don't have any particular reason to believe you, do I?

A plain list of documentation wouldn't have gone amiss - there isn't any
such included with the software, and I've not had such information given
to me since.

I've got to find what I can, find the information sources I can, and do
what I can.  I certainly don't accept that uniformed people have
definitive answers, and the replies I've been getting from this mailing
list have mostly been from poorly informed people - you're clearly not
well-informed, for example.

I might get informed.  If so, I'll probably write myself a list of
what's what, as well as some basic notes on how to learn how to manage a
TeX installation on a Mac.

I'd need to collaborate with others to get that information available to
others.  I have no plans to attempt to do so - that'd have to be done
via this mailing list, and I don't see any way I could collaborate with
`you lot'.  Too antagonistic for my liking, on the whole.

>In open-source software,  
> it can be either:

You missed out news groups.

<news://comp.text.tex> has been the most valuable (La)TeX information
source for me over the 17-18 years that I've been using LaTeX.

> - Well-written pedagogical manuals (rare).

Something like this is used to be the norm in the LaTeX world.  Look at
the OzTeX manual, look at Lamport's LaTeX book, even at Knuth's
`TeXbook' (inaccessible to most readers, but probably not bad for
`graduate computer science students', the audience for which it seems to
be written).  Even, dare I suggest?  Rather weaker stuff like the
`sectsty' package documentation?

You shouldn't go around confusing `open source' software with `purely
modern stuff'.  Don't forget that LaTeX pre-dates the Web, pre-dates
Linux, pre-dates most of the landscape of modern computing -  TeX proper
pre-dates Macs.

This stuff goes back to an era when people *expected* to read technical
manuals to learn how to use technical things.  We had proper technical
documentation right up until `some time in the 1980s', when things
started to go wrong.

`Free' software always used to come with manuals, because people simply
wouldn't have dreamt of supplying it without manuals - aside from in the
case of software supplied to do dodgy things, that is.  How could one
possibly learn how to use software without documentation?  One cannot,
so documentation has to be supplied if you want anyone to use your
software, so documentation must be supplied with software if you have
any thought of someone else using it - and why release it if you don't
want people to use it?

Documentation and software are an indivisible package in my mind: the
one must be supplied with the other.  Software without documentation is,
to my mind, useless, since it cannot be used.  This is bleedin' obvious
to me at least, and it astonishes me that not everyone sees it that way.

> - Badly-written, or non-pedagogical, manuals (often).
> 
> - ASCII ReadMe files, or man pages (too often).
>
> - Help files (too often).

You say `too often' like that - but well-written ASCII readmes and help
files can be *perfect* documentation, if properly written.  We don't
need beautiful typography: we just need the information.

This is a point to bear in mind: it doesn't always take a lot to provide
adequate docs.  The effort involved in writing decent docs is often
cited as the excuse for not providing them.  Actually, the /real/
reasons are that programmers don't like writing documentation and
they're mostly very bad at it.   But it's a bit of slog that needs
doing, and if you do it, you'll often produce better software and iron
out problems.

FWIW, the documentation that comes with LaTeXiT (for example) is a
terrible scrappy, scruffy mess - but it's *superb* from my point of
view.  Admittedly, I'm coming at it from the `I've already got a working
LaTeX installation and know all about LaTeX maths and what to do with
the founts and whatnot' point of view - but the documentation works very
well for me (despite being written by a Frenchman whose command of
English is not of the highest quality - not that I'm complaining; I
can't even ask the way to the bus-stop in French).

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

Aye, indeed!  Web was written for the purposes of `literate programming'
- combining source code and documentation in one package, which is how
come TeX the book was printed.  Docstrip (part of LaTeX2e these days)
was written for the same purpose, and others.

Documented source code is how the well-written pedagogical manuals are
/supposed/ to be presented in the (La)TeX world: that is a design
feature of great merit.

It seems odd that you don't seem to know that we're using software which
was designed to produce well-written manuals by processing the
documented source code.

Maybe you need to learn some more about TeX and its friends?  You could
profit by looking at some examples - take the manual for the sectsty
package, which is generated by running LaTeX on the source code.  This
is how it's supposed to be done.  Go on, take a look at that particular
package's documentation and tell me what you think.

Please do take the time to email me and let me know: I really would like
to know what you think of sectsty's documentation.

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

In such cases, I walk away from the software and won't touch it.

> - Mailing lists.
>
> Originally none of us had more documentation that you do.

[snip]

I started using LaTeX in 1989 (or possibly 1988), and I've not stopped.

You seem to have missed this point: I have been using LaTeX longer than
almost everyone on the planet.

Originally, I started out with Lamport's LaTeX manual and that was *it*. 

Originally, we used to have proper documentation for everything.
Recently, the old `If it was hard to write, it should be hard to use'
attitude seems to have re-appeared in the computing world - it's a
stupid idea from hard-core programmers that Macs in particular were
supposed to be working against.  I don't see any reason to accept it.

Back in the days of LaTeX 2.09, documentation was admittedly a problem -
but it was there for most things I needed to fiddle with, and I had my
friendly Unix sysadmin for the rest of it.  I provided some for the
computer lab whose LaTeX installation I wrote stuff for and maintained
with my friendly sysadmin (he did the sysadmin stuff, I did the LaTeX
fiddling).  Documentation was scarce, but we managed - *only* because
the friendly Unix sysadmin was bloody good at what he did (he didn't
claim that - he just complained bitterly about the `fuckin' *awful*...',
and `how is *anyone* supposed to...', but I saw what he did and fed him
tea and chocolate as needed).

Then we got Docstrip, and things got better.  Documented source code is
what we're supposed to have in the LaTeX world.

Up until I got MacTeX, I had two TeX distributions on my Macs: OzTeX and
CMacTeX.  Both come with  documentation, which is really rather
excellent in the case of OzTeX and `good enough' in the case of CMacTeX.

Welcome to the world of competent software distributions: there is a
correct way to do it, and providing adequate documentation is part of
that.  Failing to provide adequate documentation - well, that's just
wrong.  The demands of aesthetics are such that I for one couldn't
release software documented as poorly as that which I've met recently.
It's just the wrong thing to do from so many points of view.  So wrong
that I think it's insanity to do so - I cannot understand how anyone is
expected to make sense out of the software I've got installed, without
having a handy expert to talk to in person.

No, this is the world of (La)TeX: what we're used to getting and what we
expect is proper manuals written for being printed nicely.  This *used*
to be normal - and now you're telling me I have to just accept, on your
say-so, that the state of affairs that I've met is in any way acceptable
or excusable?  It is not: releasing software with the documentation
that's available for MacTeX is *stupid* - so stupid it's verging on
pointless.  How is anyone supposed to learn about this stuff?  Crazy,
just crazy.  But there you go: that's what I think.

Please try to understand, and please stop trying to teach a very old
hand about stuff that he knows more about than you do.

I am an old LaTeX hand: do not treat me as neophyte.  You will simply
make a fool of yourself.

The problem with documentation is not because we're using `open source'
software (or whatever the current fashionable term is for the stuff -
it's changed so many times over the years), but because the people
supplying the software have decided that it's okay to release it without
adequate documentation.

I'm here to say that it's not okay to do that.  The reasons are manifold
- but it's a modern plague, this lack of docs, and it's caused by modern
sloppiness.

> About installers
> ================
> 
> The mother of all antisocial installers is probably Adobe software.

[snip]

ROFL!

I've met more dodgy installers than some people have had hot dinners.  I
could tell you tales that'd make your hair curl.  There is *NOTHING* you
can tell me about installers that is new to me.  Trust me on this.  It's
that `grandpa sucking eggs' business again.  I've been using Macs since
about 1990 (I'd have to look up the date).  Forget trying to `teach' me
anything on this subject.

This is why I behave as I do - I have had experiences that you have not
had, and they have taught me things that you do not know.  In your
current state of ignorance, my behaviour seems irrational to you.  You
might get lucky enough to learn as much as I have, in which case you'll
see how it is I'm being perfectly sensible in my approach.

The world's a nicer place when people try to understand rather than try
to impose view-points: you really should stop trying to bludgeon me into
seeing the world your way, and try to understand my point of view.

Rowland `crabby old man' McDonnell

P.S.

Please don't respond to this on the mailing list; it's rubbish that's
cluttering up the mailing list, but I felt that you'd made some
mis-statements and suffered from some misunderstandings that needed
clearing up.
------------------------- 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/