SGML: Review of the Colby book Special Edition (Steve Pepper)

SGML: Review of the Colby book, Special Edition

Subject: Special Edition: [was Re: 1st SGML Book]
Date: Sat, 18 May 1996 16:00:46 LOCAL
From: (Steve Pepper)
Newsgroups: comp.text.sgml">comp.text.sgml
----------------------------------------- In article <4n60p6$> (Major Keary) writes (apropos Colby & Jackson: "Special Edition: Using SGML"): | The Colby book is very good and has some useful stuff on a companion CD. And in <4m5jr6$> (a review posted to a whole bunch of newsgroups: | [all kinds of positive things about the book] I have to say that this is absolutely THE worst book on SGML I have ever seen. Since I work for an SGML consulting company I need to know about the available tools - including books. So by default I always buy two copies of every new SGML book (one for me and one for the other guys at work to fight over :-). I found this one in a book store just before leaving for the SGML Europe conference last week and bought a couple of copies. After reading a few pages it became evident that the book was more suitable for party games among SGML cognoscenti than for learning about SGML. So, on the flight to Munich, my colleague Petter and I invented "Pick-a-Page". The rules of the game are as follows: *** Pick-a-Page: Abusing SGML ------------------------- Materials required: 1 copy of "Abusing SGML"; 1 or more players (book,player+). Order of play: Iteratively in ascending seat number 1. The player with the biggest ego (A) starts by shutting her eyes and opening the book at any page at random. 2. The player with the next seat number (B) has two minutes in which to find as many errors, inaccuracies etc. as possible. 3. After two minutes, the number of errors are counted up and a score is assigned to player B according to the points table below. 4. If B cannot find any errors, she is penalised with 20 minus points and the book passes to the next player, who tries to find some errors on the same page. Play continues in this way until at least one error has been found, or until every player has failed to find an error. 5. Once an error has been found (or every player has failed to find an error), the book is returned to player B, who shuts her eyes and chooses a new page at random. 6. Play continues in this way until the Fasten Seat Belts sign comes on or every player has collapsed in a fit of hysterical laughter. 7. The player with the most points at the end of the game wins and gets to be the one with the biggest ego next time the game is played. Scoring: Simple spelling mistake: 1 point Minor misuse of SGML terminology: 5 points Major abuse of SGML terminology: 10 points Error in SGML syntax: 10 points 2 or more paragraphs of bullshit: 10 points (Relatively) minor SGML error: 10 points Major SGML error: 20 points Failure to find an error: -20 points *** This game has been played a number of times and with a number of different players, and up until now we haven't found a single error-free page in the course of playing the game. In the interest of documenting these claims and showing how the points system works, here are some examples taken at random: Pages 20-21: ----------- Fig. 1.5 show a (purported) SGML document. - The caption runs as follows: "An individual instance of an SGML document contains an SGML declaration, a reference to its DTD, data, and a markup tag." (10 points) - The example itself starts with the following: <DOCTYPE Sample SYSTEM "/SGML/DTD/sample.dtd"> (10 points) - This declaration is pointed to and called an SGML declaration (20 points) (Finding the remaining errors on this page is left as an exercise for the reader. This applies to the following examples as well.) Pages 52-53: ----------- - Two new delimiter roles have been "added" to the standard: STAGC (Start Tag Close = ">") and ETAGC (End Tag Close = ">") (40 points) - These delimiter roles are said to have "abstract names" which are defined as "a quick way of referring to parts of declarations by their position". (10 points) - On the next page, "Elements" are presented using an analogy that qualifies as "two or more paragraphs of bullshit", hence 10 points. Pages 56-57: ----------- - A completely confused description of the use of LIT and LITA when specifying attribute values qualifies as bullshit (10 points) - Glaring errors in examples of what is and is not valid according to 8879 get 20 points each (e.g. the usage <SALUT ","> is OK according to the book). Pages 186-187: ------------- - "The Omittag feature of SGML is an optional function that allows you to leave out start and stop tags..." (5 points) - "In general, tags can be omitted only when their omission does not create ambiguity in the document instance. For example, take a look at the following DTD fragment: <!ELEMENT document - - ((section),para?) > <!ELEMENT section - O (para+) > <!ELEMENT para - - (#PCDATA) > This example is illegal..." No, it isn't. 20 points. Pages 336-337: ------------- - "Tip There are a couple of very common HTML errors... Probably the next biggest is getting comments wrong. These are right: <!-- some text of a comment --> <!-- another comment, with two text parts - -- of which this is the second --> ..." Common error? You said it! 10 points. I swear to you that all these pages were picked at random and that I have yet to find a page that is error-free. I have at least 20 other pages picked at random that I could have quoted from, but I don't have time to type all that stuff in. Should we laugh or cry about this? Look on the bright side: It is a sign of SGML becoming mainstream that "instant books" of this kind are starting to appear. But be warned. The book is by two authors I haven't met or heard of before, Martin Colby and David S. Jackson. Colby is apparently "a computer systems consultant in SGML systems development". Jackson is a "freelance writer" who "writes both fiction and technical manuals" (this book is obviously an example of the former :-). What is sad, however, is that there are four other names on the title page, three at least of whom have cause to be ashamed of themselves for letting their names be associated with this garbage. Those of you that already have the book, try playing the game. The rest of you should steer clear. Newcomers to SGML should buy either Liora Alshuler's "ABCD...SGML" or the book called "Read Me 1st" in the Charles F. Goldfarb Series (depending on whether it is the underlying philosophy and practical application of SGML or its syntax that interests you most). -- Disclaimer: If this posting should happen to start a new thread, I won't be able to respond until May 26. (Off travelling again.) Hope this helps (as they say :-) Steve -- Steve Pepper, SGML Architect Falch Infotek a.s, Postboks 130 Kalbakken, N-0902 Oslo, Norway tel://+47 2290 2733 fax://+47 2290 2599 "Whirlwind Guide":