From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: Gregory Leblanc , "'Norman Walsh'" , docbook-tools-discuss@sourceware.cygnus.com Subject: RE: I'm trying to set up docbook-tools... Date: Wed, 27 Dec 2000 06:36:00 -0000 Message-id: <00070716141700.19764@ehome.inhouse> References: X-SW-Source: 2000/msg00268.html 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 internal subset. The declarations stored in the file referenced by the public or seystem identifier in the DOCTYPE declaration is called the external subset 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