RE: Documentation

[MARK.WROTH@xxxxxxxxxxx (Wroth, Mark)]

I agree (perhaps because that's how I've learned what little I know, but
also because it seems to me to be a good way to hook the audience of people
who want to USE DSSSL, as opposed to learn it as a language.

It appears to me that there are several conceptual levels

1. Use DSSSL to apply basic formatting to an SGML document. Exercise: format
a web page encoded in (a subset of) basic HTML for printing.

2. Use DSSSL to reorder document components to a designer specified order
different from that present in the SGML input.

3. Use modes to show the same elements in two different formats (e.g. a
table of contents and the actual body).

4. Sort a set of siblings for output (e.g. alphabetize a telephone listing,
and then produce a list sorted by telephone number [or street address, if
you want to make the sorting problem a little more interesting]).

5. Introduce alternative approaches to the problems posed above, but using
more advanced Scheme/DSSSL features.

6. Information retrieval from an SGML document (using the processing model
to guide the search).

7. pick the next level ....

Other useful topics:

	- organizing a style-sheet (how to use style-specifications,
external specifications, etc.

	- Major existing DTD/style sheet combinations (DocBook, TEI? ...)
and how to use/customize them

	- Major DSSSL tools (e.g. Jade...) and how to get started with them

-------------
Paul Tyson <ptyso@xxxxxxxxxxxxx> writes:

> On a related topic, Adam Di Carlo wrote:
> > ... If you look at
> > SICP, the authors actually teach scheme kinda "on the sly" while
> > really teaching about abstraction, modularity, and good programming
> > style.
> > 
> > I think a DSSSL book should be written similarly.  Don't actually
> > teach Scheme per se, but just introduce the bits of syntax one by one,
> > explaining as you go.  Keep the user focussed on the problem of how to
> > render documents.  I think such an interative, approach, starting very
> > simply and working up to complex DSSSL examples, would work quite
> > well.

> Adam is spot on.  Gradus ad parnassum.  Although I don't think this
> should supplant a "Handbook" approach, it could be an inspiring
> invitation to beginning users.

Thanks.  Thinking more about this project, it really intrigues me.  An
iterative approach would really work quite well also since you can
start with really simple DTDs (a la Jon Bosak's mail DSSSL examples)
and then build up both the structure of the document, the employment
of more advanced Scheme programming features, the description of the
processing model (i.e., groves), and the complexity of what you're
trying to accomplish with DSSSL.

I think a sucessful book would also have a chapter dedicated to Norm's
DocBook stylesheets (how to use, how to tweak parameters, code
techniques Norm uses, and how to customize the stylesheets more
deeply), although I'm not sure if Norm's new docbook book covers that
or not.

I'm not sure if such a book should cover both the print style backends
and the jade transformation backends.  Probably...

God, I only wish I could clone myself so I had time to really work on
this project in a serious way...  It would be a great way for me to
really learn more about groves.


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