DD: Handbook outline so far

[Tony Graham <tgraham@xxxxxxxxxxxxxxxx>]

The following is my current outline for "The DSSSL Handbook" (and
comments on the suitability of the name are welcome).  The outline
divides the book into three parts -- introduction, references, and
so-called "real world DSSSL" -- so that related topics are grouped
together.

It is unfinished, but there is enough here that people can comment on
the suitability of the structure.

My intention remains to ask people to volunteer to take on individual
chapters, develop their structure further, and where possible divide
them into portions that multiple people can work on.  Besides the
organisational aspects, this allows people to write portions and
develop the structure of areas where they have the most expertise.

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
=======================================================================


0. PREFACE

0.1 Purpose of this book

    To cover aspects of DSSSL well enough that people can do useful
    work.  The book starts with introductions to DSSSL, has a
    reference section to help you out when you need to know something
    about the formalities, and has a "Real World DSSSL" section
    covering how to approach using DSSSL, how to organise your
    stylesheet, and how to achieve the output you want.

0.2 Who it is written for

    This is primarily a book for newcomers to DSSSL, but it should be
    generally useful.

0.3 The DSSSL Documentation Project

    Nice folks, really.

0.4 Where to find other DSSSL resources

    The SGML Web Page and James Clark's DSSSL page contain pointers to
    resources

0.5 Where to find introductions to SGML

    The SGML Web Page again for pointers to online stuff, your local
    bookstore


PART 1 -- INTRODUCING DSSSL

    Beginners start here.  This is the introduction to DSSSL, DSSSL
    concepts, and the mechanics of doing something with DSSSL.

1. INTRODUCTION - WHAT DSSSL IS ABOUT

1.1 Background
1.2 Purpose
1.3 Status
1.4 Possible future directions

    Extensions for xml-style

2. REALLY SIMPLE EXAMPLE

    Starting at the level of "hello, world".  Starting with "hello,
    world" is either de rigeur or it's objectionable because it
    perpetuates the most overused example in the history of computing,
    or maybe it's a bit of both.

    - Basics
    - Getting Started.
    - A question and answer session
    - Example 1. A simple memo. 
       - Explanation of what is taking place.
       - 1. The initial markup file
       - 2. The Document Type Definition (DTD)
       - 3. The Style Sheet

3. OVERVIEW OF DSSSL

3.1 Conceptual model
3.2 Transformation language
3.2.1 Groves
3.2.2 Transformer
3.2.3 SGML Generator
3.3 Style language
3.3.1 Conceptual model
3.3.2 Construction Rules
3.3.3 Flow Object trees
3.3.4 Flow Objects
3.4 Formatter
3.5 Expression language

4. A CRASH-COURSE IN SCHEME

5. SIMPLE STYLESHEET EXAMPLES

6. MORE COMPLEX STYLESHEET EXAMPLES


PART 2 -- REFERENCE SECTION

    This is where you go to look something up to help you out of a
    bind with the nitty-gritty of using DSSSL.  The next part, Real
    World DSSSL, is where you go for help in getting results using
    DSSSL.

7. HOW TO READ AND USE THE DSSSL STANDARD DOCUMENT
    - The parts of the standard to start with
    - Getting the most from the standard 

8. DSSSL SYNTAX SUMMARY

9. STYLE SHEET SYNTAX

10. EXPRESSION LANGUAGE REFERENCE

11. TRANSFORMATION LANGUAGE REFERENCE

12. STANDARD DOCUMENT QUERY LANGUAGE REFERENCE

13. STYLE SPECIFICATION MODEL

13.1 Flow objects
13.2 Ports
13.3 Features

    This should include a table showing what flow object classes or
    procedures depend upon each feature.

13.5 External procedures and declared characteristics

    What this means, how to specify an external procedure or declare a
    characteristic, and how to reference them in a stylesheet

13.6 Characters

    The character model in all its glory

13.7 Display space
13.8 Color

14. STYLE LANGUAGE REFERENCE

15. FLOW OBJECT CLASSES REFERENCE

    This should have some grouping of related flow object classes, and
    each group should have some introductory text about where the
    group of flow object classes fit in and how they relate to each
    other.  The alternative, of course, is a bald statement of the
    facts about each flow object class and letting the reader make
    their own conclusions about how they hang together.

15.1 Grouping
15.1.1 sequence
15.1.2 display-group
15.2 Page models
15.2.1 simple-page-sequence
15.2.2 page-sequence
15.2.3 column-set-sequence
15.2.3 multi-column
15.3 Paragraph
15.3.1 paragraph
15.3.2 paragraph-break
15.4 Table
15.4.1 table
15.4.2 table-part
15.4.3 table-column
15.4.4 table-row
15.4.5 table-cell
15.4.6 table-border
15.5 Math
      - ...
15.n Online
15.n.1 scroll
15.n.2 multi-mode
15.n.3 link
15.n.4 marginalia

16. SPECIFIC TOOL (JADE) EXTENSIONS

16.1 SGML backend
16.2 RTF extensions

17. XML-STYLE

    Summary of the purpose and status of xml-style, where to get up to
    date information

17.1 Application profile

    Summary of the application profile of the DSSSL standard required
    of a minimal xml-style implementation

17.2 Extensions

    Summary of extensions to DSSSL required to be supported by a
    minimal xml-style implementation

PART 3 -- REAL WORLD DSSSL

    Not the world's best title, but this part provides help in getting
    results using DSSSL.

18. MAKING STYLESHEETS

18.1 Analyzing the DTD

    - What to look for, what order, what can be ignored.
    - Examining, modelling the information to be styled
    - Analysis tools available to 'look at' a DTD?

18.2 Design strategies

    - Pages down to paragraphs
    - Separating common re-usable parts
    - Using inheritance    
    - Size dependencies, or how to benefit from ripple-through changes

18.3 Parameterization
18.4 Modularity

19. DSSSL TECHNIQUES

19.1 Styles
19.1 Modes
19.2 Space handling
19.3 Transformation in the style language

20. DSSSL FOR VISUAL APPEARANCE

    Another catchy title that needs changing.  This chapter covers how
    to achieve using DSSSL the objects you're used to seeing on a page
    or screen.

20.1 Pages, Headers and Footers

    How to define a page, how to create a header or footer using
    simple-page-sequence, (theoretical) discussion of page-sequence
    and column-set-sequence, how (using Jade) to reset page numbers, etc.

20.2 Paragraphs
20.2 Lists

    How to create numbered, alphabetic, and bulleted lists, how to
    creat definition lists

20.3 Tables

    Grateful reference to Anders Berglund's CALS table module, how to
    turn non-table markup into tables using the table-related flow
    object classes

20.4 Figures and Graphics
20.5 Cross Referencing
20.6 Contents and Indexing
20.7 Anchors and Links
20.8 Multi-mode
20.9 Math
20.10 Stuff in the margin
20.11 Characters, fonts, and character effects

21. USING JADE'S SGML BACKEND

APPENDIX A. EXAMPLE STYLE SHEETS

    One or more complete stylesheets, presumably for a publicly
    available DTD (probably the DTD used for the Handbook).  This
    would be most useful if it or they can be used as running examples
    throughout the book and it is possible to reference into these
    stylesheets.

APPENDIX B. COMPARISON OF DSSSL AND OTHER MECHANISMS
B.1 CSS
B.2 FOSI
B.3 Proprietary formatters

APPENDIX C. TOOL MANPAGES

    "Man"-style instructions for how to run the available DSSSL tools

GLOSSARY

    This should be one large glossary.  If it's divided into sections,
    such as DSSSL, SGML, and typesetting terms, when you don't know in
    what section the term you don't recognise belongs, you could look
    through every section before you find the term.  If the type or
    scope of the term is important, then we could put some indication
    of its category as the first part of the definition.

QUICK REFERENCE

    Definitely in SGML

INDEX

----------
$Id: hb-outline.txt,v 1.3 1997/06/20 08:58:55 tkg Exp $


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