DSSSL Documentation Project

DSSSL Handbook Outline

This is the outline for a proposed DSSSL handbook. The only portions being worked on at present are the Flow Object Class Reference and, intermittently, the Glossary.

Offers to oversee the project, contributions of sections or subsections (marked up to DocBook 3.0), offers to contribute, or suggestions for improvement are actively solicited. Please send any contributions or suggestions for improvement to [email protected].

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
0.4	Where to find other DSSSL resources James Clark’s DSSSL page contains pointers to resources
0.5	Where to find introductions to SGML Gary Simon’s discussion of SGML in “Using Text Encoding to Represent Linguistic Data” 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 CLASS REFERENCE
16.	SPECIFIC TOOL (JADE) EXTENSIONS
16.1	SGML backend
16.2	RTF extensions
17.	XSL Summary of the purpose and status of XSL, where to get up to date information
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
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.
B	COMPARISON OF DSSSL AND OTHER MECHANISMS
B.1	CSS
B.2	FOSI
B.3	Proprietary formatters
C	TOOL MANPAGES "Man"-style instructions for how to run the available DSSSL tools
	GLOSSARY
	QUICK REFERENCE
	INDEX

Sending Glossary Requests

Send glossary requests to [email protected].
Use the subject line “Glossary request”, and in the body of the message list just the requests, one per line, as in the following example:
```
To: [email protected]
Subject: Glossary request
kendot
spread
sosofo
R4RS
```

Sending Glossary Entries

Send glossary entries to [email protected].

Use the subject line “Glossary entry”. In the body of the message include the SGML for one or more entries marked up using DocBook 3.0 as shown in the following example:

<!DOCTYPE glossary PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
<glossary>
<glossentry id="gloss-kendot">
<glossterm>kendot
<revhistory>
<revision>
<revnumber>1.0</revnumber>
<date>19970620</date>
<authorinitials>Tony Graham [email protected]</authorinitials>
</revision>
</revhistory>
</glossterm>
<glossdef>
<para>Emphasizing mark used in Japanese typography</para>
<glossseealso otherterm="gloss-emphasizing-mark">
</glossdef>
</glossentry>
<glossentry>
<glossterm>kendot scoring</glossterm>
<glosssee otherterm="gloss-kendot">
</glossentry>
</glossary>

Include your name and email address in the <authorinitials> element
Glossary entries should have an ID that is “gloss-” prefixed to the term, with any spaces in the term replaced by hyphens, e.g. “gloss-kendot”
You can include more than one glossary entry in a single mail message
Use the “OtherTerm” attribute in <GlossSee> and <GlossSeeAlso> for other terms you want to reference, even if you don’t know if there is an entry for that term. If there are any broken links when I put together the SGML, I’ll just create an empty entry and add the term to the request list.
Graphics should be in TIFF or EPS formats only. Text in graphics should be 10pt Arial wherever possible.