Re: Hyperref queries

David Kastrup <dak@xxxxxxx> wrote:

real-address-in-sig@xxxxxxxxxxxxxxx (Rowland McDonnell) writes:

But the TeXbook is only any good for people who already possess `the
hacker nature'. For us `relatively normal human beings' - well, I find
it almost impossible to learn from Knuth. Oh, I get the basic, obvious
stuff - but the exercises in his TeXbook fall into two categories for
me: `Can do it almost without thinking', and `Cannot see any possible
way in which I could learn how to figure that one out'.

Almost all the times I've `got something tricky' from the TeXbook, it's
because I've sat down and wrote my own bloody documentation,
painstakingly, tiny piece by tiny piece, assembling it from disparate
information sources. Very, very hard work indeed.

TeX documentation really does need to be re-written for people who are
*not* expert computer programmers with a particular academic
background...

That's like saying a car maintenance manual should be rewritten for
people who have no mechanics background.

Nonsense! It's equivalent to suggesting that a car manintenance manual
should be written for those who are not expert in maintaining cars but
do understand mechanics.

And that is how they are in fact written.

Likewise, computer documentation should be written for people who are
not expert in the particular field that the documentation is covering
but do nontheless `know about computers' in the way that a person who
doesn't know all about maintaining (say) a 1997 Vauxhall Astra[2] 1.4l
nevertheless `knows a bit about mechanicking'.

TeX is not a system for the non-technically inclined.

Indeed - I can work with car maintenance manuals, you know. I can work
with Lamport's LaTeX manual. I can work with all technical
documentation I've met in fields that I understand to an extent -
provided that the tech docs are in English and written before about
1980...

And that includes the very, erm, `1970s Japanese writing a manual for
foreign devils' Kawasaki manual for the KH250 my mate had (student
years). KH250s were supposed to have engines detuned compared to the
earlier S1 250cc triple from Kawasaki. This particular KH250 had been
modified... The neighbours didn't like it, let's put it like that[1].

I have Scroggie's Radio Laboratory Handbook, and that dates back to the
1930s. Makes sense to me, that does. So do the Haynes manuals for the
motorcycles (I've got a Clymer manual for one of them, which makes
somewhat less sense; apparently, Clymer's got better since that
particular bike manual was published in about '85; for the Honda
VF500FII).

(I possibly have some German technical documentation somewhere - never
figured it out, even when I asked my school German teachers. Well, they
knew nothing about electronic engineering, did they? And I've met
Russian tech docs, which just make me laugh. Can I so much as read
Cyrillic? Not as such, not really...)

When I was a student, I built my own stereo audio amp to my own design
(using bits which I will absolutely never admit to having scabbed from
the university lab and no it wasn't very good but it did work well
enough). Are you trying to suggest that I'm not somehow not technically
inclined? I'm a chap who's stripped down and rebuilt rather too many
motorcycles and is quite happy with a soldering iron in hand, and you
seem to me to imply that I might not be technically inclined? Hmm...

What I don't have is a formal, academic background in computing
technology - my degree was in physics, and so we took a slightly more
ad-hoc approach to computing than the CS people.

It is a toolbox,
not a solution.

Just like the toolbox in my garage - which any technically competent
person can learn to use without any bother at all, and can do useful
work on the motorcycles in the garage using the manuals in the garage,
if they have any technical aptitude at all. Unlike with TeX...

Another difference with TeX is that it's not just a toolbox - it's more
akin toolbox and construction materials. You can't do a thing with a
toolbox alone - it's got to have material to work on.

Look, you can build structures using TeX, yeah? Right. I'd say that a
better analogy than `toolbox' would be to describe TeX as more like a
kit of parts that you need instructions for to use properly - but those
who already know how to work with those parts don't need such involved
instructions.

In car maintenance terms, one could say that the people who can use TeX
documentation are those who have already attended a car maintenance
course and learnt all about maintaining lots of different specific car
models; the rest of us are just `okay at mechanicking' and need a proper
manual - which the elite doesn't see any need for, because *they*
already know most of what needs to be learnt due to their intensive
technical training in the specific field concerned.

LaTeX comes closer to that approach, ConTeXt presumably
also (except there is no documentation for the user, bloody or not, as
far as I am able to figure out).

LaTeX requires a high degree of technical competence to use at all.

LaTeX alone is no solution - the combination of (in no particular
order):

`LaTeX + (computer and operator) + final output device +
(operator's knowledge) + LaTeX documentation'

adds up to a solution, so it does. LaTeX on its own does nothing.

The apparent paucity of ConTeXt documentation is why I've not even
looked to see if I've got ConTeXt installaed.

I'm trying to figure out XeTeX. That's got documentation that does
cover all I need, as far as I can tell - but it does need re-writing to
be useful for me, damnit. <sigh> No complaints about the XeTeX docs as
such - but... Oh boy. It never used to be this hard to learn how to
use a computer program, and it's not changes in me that are the problem:
I've got old-style docs, and new-style docs, and it's clear that it's
the style of modern documentation that is the problem.

Rowland.

[1] For those who don't know: Kawasaki triples from the 1970s are the
epitomy of the motorcycle as a noisy, smelly, dirty, unreliable,
excessive fast, dangerous machine for lunatics. They're *great* - that
KH might not have got much above 90mph, but by god it got there quickly
making a glorious sound while it was doing so, if you happen to like
screaming smelly two strokes. I do; neighbours don't. My current
bike's a nice civilised Honda; my wife rides a similarly civilised
Suzuki.

[2] They make 'em just down the road.

--
Remove the animal for email address: rowland.mcdonnell@xxxxxxxxxxxxxxx
Sorry - the spam got to me
http://www.mag-uk.org http://www.bmf.co.uk
UK biker? Join MAG and the BMF and stop the Eurocrats banning biking
.

Relevant Pages

  • Man vs. Info: documenting the software
    ... How do I make a hard copy of the documentation for the GNU Libc ... The Info manuals are much closer to a “single document” ideal ... S> As long as a large number of packages have man pages, ...
    (comp.unix.shell)
  • Re: Man vs. Info: documenting the software
    ... IS> How do I make a hard copy of the documentation for the GNU Libc ... S> And again, I already addressed this: Manuals like that, sure, make ... IS> tutorials as well. ...
    (comp.unix.shell)
  • Re: Man vs. Info: documenting the software
    ... S> search with a single search command is more useful to me. ... And again, I already addressed this: Manuals like that, sure, make them ... And this is why the GNU attitude is harmful; ... for which the documentation is in an awful state. ...
    (comp.unix.shell)
  • Re: DTV antennas?
    ... of the customer base has some form of written or on-screen learning or ... How about they can't find the documentation to read? ... It's not easy, rough reading, totally ... Manuals that are full of illustration and examples work ...
    (sci.electronics.design)