Re: DSSSL Documentation Project?

Subject: Re: DSSSL Documentation Project?
From: Tony Graham <tgraham@xxxxxxxxxxxxxxxx>
Date: Mon, 9 Jun 1997 22:26:20 -0400 (EDT)
At 9 Jun 1997 10:46 +0100, Sebastian Rahtz wrote:
 > I am all in favour of a DSSSL Documentation Project. But I come up
 > against a problem - what would be really useful would be a copy of the
 > standard with a TOC, an index, and running heads. And we are

The front matter -- including a ToC -- for the PDF and Postscript
versions of the standard are on the WG8 ftp site as, I believe,
dsssl96f.pdf and dsssl96f.ps, respectively.

That only addresses the least part of your problem, however, and I
don't know how you're going to get running heads and (wonder of
wonders) an index unless James Clark writes the DSSSL analogue of "The
SGML Handbook".

 > constrained from doing that by copyright etc. The indices by eg Harvey
 > Bingham are nice, but i'd really like them more tightly bound to the
 > text, so that I end up with a book I can keep open on my desk.

The text of the standard is useful to you, but I'm postulating that
there are people starting out with DSSSL who want something simpler
with more hand-holding than the precise wording of an International
Standard.

 > Half the time you want a cookbook; the other half of the time you want
 > a reliable reference. Well, actually what I really want is the
 > reliable reference, but with more worked examples _in situ_

Half the time I do want a cookbook and all of the time I do want a
reliable reference with lots of worked examples, and I'm sure there
are more than just us two who want the same thing.

My premise for starting this thread is that not only are there many
people who want that sort of thing, but there are many people who are
able (and, I hope, willing) to contribute some part towards creating
it.  As yet there hasn't been a way for a small effort to make a
visible difference, and we are fortunate that some people have had the
time and the energy to each singlehandedly create one of the tutorials
or reference pieces that we have so far, but we are still lacking the
"reliable reference with lots of worked examples" and, I would hazard,
we are still lacking sufficient entry-level material.

Think of what I am proposing as a mosaic (the thing made of tiles, not
the web browser): the mechanism for coordinating the effort and
disseminating the results is the wall on which the mosaic is built;
the way we structure the documentation into "man pages", cookbook
items, tutorial sections, introductions, and detailed discussions for
the DSSSL language lawyers, etc., is the pattern for the mosaic; and
the individual items of documentation are the tiles making up the
mosaic.  It doesn't matter if some pieces are bigger than others and
it won't look like much of a picture to begin with, but you can
eventually make something quite good out of a lot of disparate pieces.

Regards,


Tony Graham
=======================================================================
Tony Graham, Consultant
Mulberry Technologies, Inc.                         Phone: 301-231-6931
6010 Executive Blvd., Suite 608                     Fax:   301-231-6935
Rockville, MD USA 20852                 email: tgraham@xxxxxxxxxxxxxxxx
=======================================================================


 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist


Current Thread