RE: I'm trying to set up docbook-tools...

[Eric Lee Green <eric at badtux dot org>]

On Fri, 07 Jul 2000, Gregory Leblanc wrote:
> I have to say that I've been reading this thread with a fair bit of
> interest, since there are some huge holes in documentation for actually
> doing useful things with DocBook.  As for this jargon thing, I don't think
> that there is ANY hope of being able to usefully write a Definitive Guide on
> DocBook without a lot of fairly specific jargon.  

Quite obviously. The question then becomes one of how you handle the jargon.
For example, here's a glossary entry from DB:TDG:

entity: A name assigned (by means of a declaration) to some chunk of data so
that it can be referred to by that name; the data can be of various ckinds (a
special character or a chapter or a set of declarations in a DTD, for
instance), and the way in which it is referred to depends on the type of data
and where it is being referenced: SGML has parameter, general, external,
internal, and data entities.

Here's a glossary entry from an internal document that I wrote:

Encryption
       A method of scrambling data such that it cannot be read (see decryption)
without possession of the proper passphrase or key.  

Note that a) it's short, b) it's precise, c) it doesn't go into details about
various methods of encryption etc. Though further on, we get the following
glossary entry:

Private Key (Symmetrical) Cryptography
       A mechanism via which each end of a communication share a common key,
which is used by both ends to both to encrypt and decrypt the data. The common
key is  usually transmitted using the (much slower) process of public key
cryptography (see below), which allows communications to take place without
transmitting a common key in a way that can be intercepted.   

This glossary entry is less satisfactory, but still is much more readable than
the typical DB:TDG glossary entry. 

Note that this glossary, as you might gather, deals with the very technical
details of encryption, a field which has its own arcane terminology (quick,
what's a Feistel-network symmetric cipher with a 64-bit block length and
128-bit key length and key-dependent S-boxes?! And what about our IV, is it
necessary with CFB feedback mode to use a random IV, or will a unique one
in counter mode provide adequate protection?).  But no matter how arcane the
terminology, it is possible to express it in a manner that is both easy to read
and accurate.  Unfortunately, in many places DB:TDG appears to be written under
the delusion that it is impossible to be both easy to read and accurate.  For
example, page 17:

"These declarations form what is known as the <i>internal subset</i>. The
declarations stored in the file referenced by the public or seystem identifier
in the DOCTYPE declaration is called the <i>external subset</i> and it is
technically optional. ..."

What's a declaration? what's a public identifier? What's a system identifier?
What's a subset? Who's on first? While accurate, the above paragraph is totally
incomprehensible to someone who is not well versed in the arcane vocabulary of
SGML. 

Meanwhile, a snippet from one of my own documents:

"The Diffie-Hellman authentication chat is succeptible to man-in-the-middle
attacks (see Schneir, p516). In response, shared-secret chats such as  SPEKE
were created, but those will not work in our application. In order to deal with
the problem of man-in-the-middle attacks, the server public key X will be by
default deployed as a hard-coded public key and the user will be cautioned to
initiate the initial connection as soon after installation time as possible. As
long as the network is secured at the time of the initial chat, future
transactions are no longer succeptible to man-in-the-middle attacks. Note that
all public key encryption methods which do not use a shared secret or a
hard-coded public key are succeptible to man-in-the-middle attacks (that is why
'ssh' asks you for the password - a shared secret - until the connection has
been authenticated both ways with a password). The SSL protocol, by contrast,
relies upon having a hard-coded public key (the public key of the certificate
server), an Internet path to the certificate server, and a secure certificate
server. The latter two problems are why we do not use SSL here. "

Not the most clear of passages, and it refers to another text for a definition
of a man-in-the-middle attack, but it does have some attributes of good
documentation: it refers to the way some other program that the user is
familiar with operates (this is in a highly technical document intended for
network engineers), it compares and contrasts it with other ways of handling
the problem, and it does tell how the problem is solved in a real-life
instance.  There's other possible models that could have been discussed (such
as the PGP "trust" model), but that's hardly relevant. 

> vernacular for the author and readers.  The problem here, I think, is that
> it's bloody hard to figure out which words mean what without working with it
> for a good while.  I've finally figured out what DSSSL is, and where all of
> the pieces fit together, but it's NOT easy to do, and I don't think I'm an
> idiot (which may or may not be relevant).  DocBook: TDG is NOT a gentle
> introduction to DocBook, or to writing using DocBook.  It's a reference
> guide, and as such, must use terminology suitable for people using a
> reference guide.  I don't recall finding a good glossary of SGML terms, or a
> good flow-chart (doesn't anybody use them for anything anymore?) of how
> publishing a DocBook document work anywhere that I looked.  These two things
> together would probably help clarify a lot of things for people getting
> started with DocBook publishing.

Indeed :-). There is a glossary. But it confuses more than it enlightens. For
example:

"cooked: "Cooked" data, as distinct from "raw", is a collection of elements and
character data that's ready for presentation. The processor is not expected to
rearrange, select, or suppress any of the elements, but simply present them as
specified. Also see RAW. "

Utterly incomprehensible. 

> I have to say that while it may be obvious to you, it is NOT to some other
> people.  I happen to find the flow of most chemical equations totally
> intuitive, whereas Norm probably finds the flow of taking a DocBook document
> and turning it into HTML totally intuitive.  

Indeed.  That's why I was a better math teacher than I was a computer science
teacher -- for me, the notion of describing a problem in a terse English subset
such that it can be executed by a computer is natural and totally intuitive,
whereas for my students, it was not. Meanwhile, never having been the math
maven, I found that presenting mathematic concepts in a clear, concise,
understandable manner not only helped the students, but it helped organize my
thinking about mathematics.  Mathematics, not being intuitive to me, was much
easier for me to explain an an easy-to-understand manner that was both
accurate and accessible.  Yes, I regularly cursed the authors of the math texts
that I was forced to use (or not use, actually, in my case -- I taught out of
notebooks, because high school math texts are so horrible). 

--
Eric Lee Green      There is No Conspiracy
eric@badtux.org     http://www.badtux.org