🚀 go-pugleaf

<!--
	This is the entire text of the review that I mentioned in my
	previous article.  SGML DTD and markup is entirely my own.
-->

<!--
	Typed in from <TAG> Issue 16, October 1990 and distributed
	with permission from the Graphic Communications Association.
-->

<!DOCTYPE article [

<!ENTITY trade SDATA "(TM)" -- trade mark symbol -->

<!ENTITY % phrase "cit|q|fp|hp">

<!ELEMENT article		- -  (title, author, ingres?, h1+, authinfo?)>
<!ELEMENT (author|authinfo)	- O  (#PCDATA)>
<!ELEMENT ingres		- O  (p+)>
<!ELEMENT h1			- -  (h1t, p*, h2*)>
<!ELEMENT h2			- -  (h2t, p*, h3*)>
<!ELEMENT h3			- -  (h3t, p*)>
<!ELEMENT (title|h1t|h2t|h3t)	- O  (#PCDATA|(%phrase))*>
<!ELEMENT p			- O  (#PCDATA|list|(%phrase))*>
<!ELEMENT list			- -  (item+)>
<!ELEMENT item			- O  (#PCDATA|p)*>
<!ELEMENT (%phrase)		- -  (#PCDATA|(%phrase))*>
]>

<article>

<title><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&trade; 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>