<cit/Practical SGML/ by Eric van Herwijnen Kluwer Academic Publishers, 1990 <author>Review by Deborah A. Lapeyre</author> <ingres> <p> <cit/Practical SGML/ was written to fill a specific niche in the SGML literature. The author, Eric van Herwijnen, feels that current published reports of SGML indicate a lack of practical SGML experience. The <q>principal aim of <cit/Practical SGML/ is to help and encourage authors, document managers, and computer programmers to start using SGML</q> by showing them how other people use it.</ingres> <h1>Contents <p>The book is divided into three parts:</p> <h2>Part I: Getting started with SGML <p> This portion of the book starts simply, by defining SGML and providing basic information; what SGML is, why use it, when to use it, and what SGML is not. The book then introduces the concept of a DTD and explains the document components (such as elements, attributes, and entities) that comprise a tagged instance, introducing a simple office memo which is used a continuing example throughout the book. The next chapter explains in detail the SGML declarations that comprise a simple DTD. The next chapter discusses DTDs themselves; how to read them, tips for writing DTDs, and pitfalls to avoid. <p> Part I of the book is most appropriate for a person who finds ISO 8879 difficult to read. Tables are used to describe the ISO 8879 production rules. In the tables, SGML productions are described in English with an example and then a table defines all the parts of the example. The section on attribute declarations includes a particularly good discussion on <q/what is an attribute/ that uses three different <q/type=/ examples to zero in on the confusion most beginning users have with the phrase <q/a characteristic quality, other than type or content/.</h2> <h2>Part II: Advanced SGML <p> is full of examples of SGML features and constructs. For example, this section includes: <list> <item>Examples of CGM and Postscript™ inclusions in an SGML file; <item>Extensive examples of the use of Marked Sections, including the constructions of multilanguage SGML documents; <item>The standard memo example used throughout the book, done as a shortref/usemap example; <item>Examples of mathematical formulae coded in TeX, EQN, the ISO 9573 SGML tagset, and the AAP Math SGML tagset; and <item>A DTD for describing CGM and GKS graphics. </list> <p> This books fills the experience gap by sharing (in various levels of detail) specific, concrete, practical experiences with many current SGML applications. Some SGML applications are described in considerable detail, including user interface screens, DTD fragments, and computer program code. In this way, <cit/Practical SGML/ allows the reader to participate directly in the author's SGML experiences, including the experience of using SGML to produce the book itself! The sections on minimization and start and end records are quite good, reiterating the wording of ISO 8879, but giving short, clear examples for each item discussed.</h2> <h2>Part III: SGML Implementation <p> gives very brief overviews of the SGML parsing function, translation out of SGML some of the ways SGML tags get into files, the Shouten document database example, SGML and CALS, and SGML and EDI. This section is not all-inclusive, and does not try to be. For example, the section on parsers lists <q/some SGML parsers/ and the translation programs discusses <q/the translation possibilities of some SGML products/. </h2></h1> <h1>Useful Features and Strengths <p> <list> <item>Each chapter ends with a quiz to <q/Test Your Understanding/. The answers are given in the back of the book. Don't skip these quizzes; they sometimes bring up entirely new points not covered in the chapters! <item>Each chapter (even the glossary) also included as bibliography and these mini-bibliographies are one of the most interesting features of the book. <item>The appendices include an explanation of the author's experiences and lessons learned when publishing the book <cit/Practical SGML/ using SGML, the DTD that was used to produced the book, some entity definitions for use with TeX, and a very good <q/How to Read ISO 8879/. (This appendix explains both how to read an SGML syntax production and why the average reader shouldn't bother.) <item>The glossary definitions are simple English definitions, non-circular, succinct, and much easier for a beginner to understand than the definitions in ISO 8879 (<fp/e.g./, <q>element: A part of a document which is a logical entity such as a chapter, section, a title, a paragraph, and so on.</q>). </list></h1> <h1>Technical Accuracy <p> I read this book with my copy of ISO 8879 in hand, spot-checking the definitions and declarative statements. This book is technically accurate and always includes all the updates from Amendment One. The DTD examples (at least all the shorter ones) parse cleanly. The REXX program run. The FORTRAN examples compile cleanly. Yes, there are errors in this book. But they are very few and likely to be caught in by an errata sheet before the next edition.</h1> <h1>Nits and Picks <p> I feel that Part I of the book should be called <q/A Programmer's Guide to SGML/. In a successful attempt to avoid SGML jargon, this book makes use of concepts familiar to programmers but not too many editors, typesetters, writers, lawyers, etc. Macros, tree traversal, and pre-order (for example) were explained briefly, but strong data typing and floating point numbers were never explained at all. I gave this book to four SGML neophytes (admittedly a small sample). The <q/C/ programmer was the happiest, reporting <q/the only good explanation I've seen that tells me what SGML is all about/. Two of the others thought the book got too technical too fast, and should not be given to real beginners. <p> Perhaps because of the publishing background many SGML readers are assumed to have, we (in general) have a reputation for being critical of details. So, the basic question that will be asked is <q/Are there typos in this book?/ Of course there are, rather a lot. But although numerous, the typos are usually in places that don't matter, such as the introductory sentences in the general text. The typos are almost never fatal and never (that I noted) in the parseable examples. The meaning is never obscured, even when the grammar or syntax has vanished beneath a typo. <p> Second picky question: Are there errors in the quiz answers? Yes, but they are gross errors, not fine errors that could trip an unwary beginner. The answers are an accurate reflection of the chapter text. But in Chapter 3, for example, the answer to question six was omitted, causing all the rest of the answers to be misnumbered. <p> Still another nit: The index was generated by IBM BookMaster. Warning for those of you who have never used a Script index: if you can't find the reference on the page cited, look on the next page! <p> More small complaints: The headings of the document don't always match the text. For example there is a section called <q/Documenting an Application/. The paragraph below the heading explains that what the author means is <q/explaining the DTD/. Now a DTD is not an application, and the paragraphs that follow this heading are neither good application documentation nor good DTD documentation. But the text is a fine example of <q/How to Read a DTD/, a very good <q/explanation of a DTD/, which was the author's stated intent. <p> The book can sometimes be confusing, as when it gives a black and white picture of a color system, explains that the colors are crucial, and then doesn't explain the coloring system. But to pick on these flaws and ignore the book because of them is to miss the point and purpose of this volume. This book is not rigorous and was not intended to be. This book is an overview of some basic, practical SGML application (largely, but not exclusively IBM) that are happening in the SGML world right now.</h1> <h1>Summary <p> This book is not a perfect book. This is not the general SGML introduction that explains everything that all SGML users are still looking for. This book is a very personal volume, sort of <q>Travels Through the Land of SGML Software and What I Found There</q>. You will want to read it for the same reason that you read any other travel volume: to acquire vicarious experience before trying out the real thing; to act as a guide to unfamiliar and uncharted territory; to compare another traveler's impressions with your own. This book packs a lot of SGML application experience into one volume. <p> Along the way, the author describes some fascinating SGML application, details some of the very real problems an SGML'er is likely to face, provides some useful pointers and DTD samples, and provides a good programmer-oriented introduction to SGML.</h1> <authinfo> Ms. Lapeyre is a Senior Consultant with ManageMatics Corp. </article> -- [Erik Naggum] <enag@ifi.uio.no> Naggum Software, Oslo, Norway <erik@naggum.uu.no>